Get account balances

The caller must be allowed to view wallets in a company or broker workspace (or be an admitted LP taker). API keys and OAuth clients additionally require treasury_read; this read never authorizes a payment. Read through the connection holding the account’s balance credential, a configured one first (its connectionId and execution type are in the body); the observation, staleness and display-value rules are those of the venue-connection balance read, so a balance key held only by a disabled venue returns its last-known balance. 409 VENUE_ACCOUNT_FUNDS_IN_WALLETS for an account whose money is in the company’s own wallets, VENUE_ACCOUNT_REVERIFY_REQUIRED when no current key holds its balance, VENUE_ACCOUNT_REVOKED for a disconnected account, VENUE_ACCOUNT_VENUE_UNKNOWN when its venue is not recognised; 404 VENUE_ACCOUNT_NOT_FOUND. 403 VENUE_READ_AUTHORITY_REFUSED whenever the caller’s read authority has ended, whether the check before the read or a recheck during it sees it (reason authority_ended: the credential is revoked or expired, or no longer carries treasury_read; reason permission_withdrawn: its owner lost permission to view wallets, its membership or taker admission); a session that has itself ended answers 401.

GET /api/v1/workspaces/{workspaceId}/venue-accounts/{venueAccountId}/balances

Read the venue account's balances at its venue

cURL

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

200

{
  "accountBindingStatus": "<string>",
  "connectionId": "<string>",
  "controlRevision": 123,
  "credentialRevision": 123,
  "executionOffering": "basic",
  "executionTypeId": "<string>",
  "providerSite": "<string>",
  "reason": "<string>",
  "source": "provider_api",
  "spendingReadiness": "supported",
  "state": "supported",
  "workspaceId": "<string>",
  "balances": [
    {
      "asset": "<string>",
      "free": "<string>",
      "total": "<string>",
      "assetMarker": {
        "assetClass": "crypto",
        "nativeAssetId": "<string>",
        "symbol": "<string>",
        "network": "<string>"
      },
      "available": "<string>",
      "locked": "<string>",
      "usdPriceSource": "<string>",
      "usdValue": "<string>"
    }
  ],
  "expiresAt": "2023-11-07T05:31:56Z",
  "observedAt": "2023-11-07T05:31:56Z",
  "reasonCode": "<string>"
}

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

Current company or broker workspace

venueAccountId · string · required

Response

200

application/json

The wire shape of GET …/venue-accounts/{venueAccountId}/balances.

accountBindingStatus · string · required

connectionId · string · required

controlRevision · integer<int64> · required

credentialRevision · integer<int64> · required

executionOffering · enum<string> · required

How a venue is integrated: basic or advanced.

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

Available options: basic, advanced

executionTypeId · string · required

The execution type (compiled spec id), not the catalogue Venue.

providerSite · string · required

reason · string · required

source · enum<string> · required

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

Available options: provider_api, provider_api_last_known, build_support, on_chain

spendingReadiness · enum<string> · required

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

Available options: supported, unsupported, unverified, stale, unavailable

state · enum<string> · required

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

Available options: supported, unsupported, unverified, stale, unavailable

workspaceId · string · required

balances · object[] | null

null means no observation; [] means an actual empty snapshot. Inactive accounts may return historical values only with stale state and provider_api_last_known provenance. These never authorize spending.

Show child attributes

expiresAt · string<date-time> | null

observedAt · string<date-time> | null

reasonCode · string | null

A named balance-read refusal, distinct from a missing observation.