Discovery and Balances

Overview

This guide shows the published SYSTEM sequence for discovering wallet-capable connections, reading provider account details, and loading balances and activity. The repo does not currently publish a generic /system/wallets surface, so discovery starts with Slash connections and account IDs.

Prerequisites

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

Shared Headers

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

Step-by-Step Flow

1. Discover wallet-capable connections

API endpoint: GET /web/v1/workspaces/{workspaceId}/slash/connections This is the published discovery step because each connection anchors provider accounts.

curl 'https://api.example.com/web/v1/workspaces/WS_001/slash/connections' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":[{"bizId":"conn_abc123","connectionName":"Primary Slash Connection","connectionStatusName":"ACTIVE","slashAccountId":"acct****efgh"}]}

2. Read the selected connection

API endpoint: GET /web/v1/workspaces/{workspaceId}/slash/connections/{connectionBizId}

curl 'https://api.example.com/web/v1/workspaces/WS_001/slash/connections/conn_abc123' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"bizId":"conn_abc123","connectionName":"Primary Slash Connection","connectionStatusName":"ACTIVE","slashAccountId":"acct****efgh"}}

3. Load the top-level balance summary

API endpoint: GET /web/v1/slash/connections/{connectionBizId}/balances/top-level Use this for dashboard summary cards and overall balance widgets.

curl 'https://api.example.com/web/v1/slash/connections/conn_abc123/balances/top-level' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"accountId":"acct_abc123","available":15000.0,"pending":500.0,"total":15500.0,"currency":"USD"}}

4. Load wallet details

API endpoint: GET /web/v1/slash/connections/{connectionBizId}/accounts/{accountId} Use this for account metadata such as provider status and routing identifiers.

curl 'https://api.example.com/web/v1/slash/connections/conn_abc123/accounts/acct_abc123' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"id":"acct_abc123","status":"active","name":"Primary Account","account_number":"1234567890","routing_number":"021000021"}}

5. Load account-level balances

API endpoint: GET /web/v1/slash/connections/{connectionBizId}/accounts/{accountId}/balances This returns detailed balance items in cents.

curl 'https://api.example.com/web/v1/slash/connections/conn_abc123/accounts/acct_abc123/balances' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"items":[{"type":"USD","available_balance":{"amount_cents":1500000},"posted_balance":{"amount_cents":1450000}}]}}

6. Load wallet flows

API endpoint: GET /web/v1/slash/connections/{connectionBizId}/transactions This is the published activity feed for wallet movement.

curl 'https://api.example.com/web/v1/slash/connections/conn_abc123/transactions?status=completed&from=2026-03-01T00:00:00Z&to=2026-03-29T23:59:59Z&page=1&pageSize=20' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"items":[{"id":"txn_abc123","status":"completed","amount":5000,"currency":"USD","createdAt":"2026-01-15T10:30:00Z"}],"page":1,"pageSize":20,"total":1}}

Decision Points

1. use top-level balance for summary widgets and account balances for detailed pages
2. keep provider-native snake_case fields if the frontend renders Slash payloads directly
3. use transaction aggregation when the UI needs totals instead of line items
4. treat the connection list as the discovery source when no generic wallet list exists

Error Handling

1. 4040 means the connection or account identifier is wrong or stale
2. 4010 usually means the JWT is expired, not that the wallet is gone
3. if connection discovery fails with 4030, confirm workspace permissions first
4. normalize top-level amounts and cents-based account balances before comparison

Next Steps

1. Create and Track Transfers
2. Default Workspace and Membership
3. Transfers Guide