Wallets Guide

Overview

The SYSTEM wallet story in this repo is currently documented through the slash-connection, slash-wallet, and slash-transaction endpoint families rather than a standalone /web/v1/consumer/wallets/* surface. In practice, that means wallet discovery begins with a workspace-scoped Slash connection and then fans out into account, balance, and transaction calls.

What This Domain Covers

1. discovering wallet-capable Slash connections for a workspace
2. reading account-level wallet details
3. retrieving top-level and account-level balances
4. listing wallet activity through transaction endpoints
5. connecting wallet context to transfers and reconciliation

Common Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. workspace ID for connection discovery
4. Slash connection business ID
5. account ID inside the selected Slash connection

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
Authorization: Bearer <accessToken>

Published Endpoint Families

Connection discovery

1. GET /web/v1/workspaces/{workspaceId}/slash/connections
2. GET /web/v1/workspaces/{workspaceId}/slash/connections/{connectionBizId}

Wallet detail and balances

1. GET /web/v1/slash/connections/{connectionBizId}/balances/top-level
2. GET /web/v1/slash/connections/{connectionBizId}/accounts/{accountId}
3. GET /web/v1/slash/connections/{connectionBizId}/accounts/{accountId}/balances

Wallet flows

1. GET /web/v1/slash/connections/{connectionBizId}/transactions
2. GET /web/v1/slash/connections/{connectionBizId}/transactions/{transactionId}
3. GET /web/v1/slash/connections/{connectionBizId}/transactions/aggregation

Typical Developer Sequence

1. list workspace connections
2. inspect the selected connection and capture the provider account ID
3. read the top-level balance for dashboard summary cards
4. read the account detail and account balances for wallet pages
5. load transactions for recent wallet flows and drill down into a specific item

Decision Points

1. whether the UI should start from workspace connection selection or from a previously saved default connection
2. whether to display top-level balance only or also account-level balances in cents
3. whether transaction history is needed in paginated list form or aggregated summary form
4. whether the selected connection should also drive transfer creation

Error Handling

1. 4040 on Slash wallet or transaction endpoints usually means the connection or account ID is wrong, not that the user lacks general portal access
2. response fields on Slash-backed endpoints often use provider-native snake_case; preserve them in the client model
3. a missing workspace:manage permission will block connection discovery even when the wallet endpoints themselves accept a JWT
4. do not invent a generic wallet list endpoint if the account IDs are only discoverable through connection metadata in your deployment

Next Steps

1. Discovery and Balances
2. Transfers Guide
3. Workspace Guide