List workspace balances

Cache-only balance observations across readable workspace wallets and venue accounts. Each wallet accountId is its walletId; venue accounts retain their native venueAccountId. amount is total holdings in exact decimal asset units, asOf is the source observation time, and freshness distinguishes stale or partial observations. No provider request or refresh is started. Accounts without a readable observation are named in unavailable with a cause code, never a fabricated zero. Bank balances are unobservable. Personal wallets are excluded. The wallet resource policy must allow read_balances; a venue account needs the caller to be allowed to view wallets, in a company or broker workspace or as an admitted LP taker, exactly as its own balance read. Required API-key scope: treasury_read; an OAuth client needs the same scope. Hidden accounts affect neither rows nor cursors. unavailable is repeated on each filtered page. Cursors bind to the workspace, caller, filters and ordered visible row identities; restart if those identities change.

GET /api/v1/workspaces/{workspaceId}/balances

Read balances across workspace accounts

cURL

curl --request GET \
  --url https://api.tetrafi.io/api/v1/workspaces/{workspaceId}/balances \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "accountId": "<string>",
      "accountKind": "wallet",
      "amount": "<string>",
      "asOf": "2023-11-07T05:31:56Z",
      "asset": "<string>",
      "freshness": "<string>",
      "id": "<string>",
      "chain": "<string>",
      "nativeAssetId": "<string>"
    }
  ],
  "nextCursor": "<string>",
  "unavailable": [
    {
      "accountId": "<string>",
      "accountKind": "wallet",
      "reasonCode": "<string>",
      "asOf": "2023-11-07T05:31:56Z",
      "asset": "<string>",
      "chain": "<string>"
    }
  ],
  "incomplete": {
    "reason": "accessSettingsUnavailable"
  }
}

Authorizations

bearer_authapi_key

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Scopes

treasury_read · bearer_auth

treasury_read · api_key

Headers

X-Workspace-Id · string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Path Parameters

workspaceId · string · required

Workspace ID

Query Parameters

asset · string

accountKind · enum<string>

The kind of account a balance is held in. Clients tolerate future kinds.

New values may be added; treat unknown values as other.

Available options: wallet, venueAccount, bankAccount

accountId · string

limit · integer<int32>

Required range: x >= 0

cursor · string

Response

200

application/json

items · object[] · required

Show child attributes

nextCursor · string | null · required

unavailable · object[] · required

Filtered readable accounts whose balances cannot be stated. Repeated on every page; never replaced with zero or a successful empty observation.

Show child attributes

incomplete · null | object

Unreadable access settings cannot establish affected account visibility.

Show child attributes