Skip to content
Seismic Orchestration

GET /accounts/:id/balance

The balance of a virtual account. Seismic keeps the stored balance record in sync as funds move (deposits landing, payments settling, account updates) and serves reads from that record. as_of says when the balance was last refreshed.

The first-ever read of an account that has never been synced (for example, an account created before balance sync existed) is backfilled with a fresh read at request time, so that one call may take a moment. After that, reads are instant and event-driven sync keeps the number current.

Balance only exists for origin: "virtual" accounts, accounts provisioned for you that hold funds. External accounts return 400: their funds sit at your own bank or wallet, so there is nothing for Seismic to report.

Scoped to the org bound to the credential. Accounts owned by a different org return 404.

Need the latest number on demand: a dashboard "refresh" button, a reconciliation step? POST /accounts/:id/balance/refresh forces a fresh upstream read, rate-limited to once a minute per account.

The same three fields also appear inline on the Account record (balance, available_balance, balance_as_of). Single-account reads (GET /accounts/:id and the per-kind GETs) run the same backfill, so they self-heal a never-synced account too. List reads serve stored values only. This endpoint is the dedicated balance read, and the only one that fails loudly (503) when the backfill can't complete. The account reads degrade to omitting the balance fields instead.

Response 200

FieldTypeNotes
account_iduuidThe account the balance belongs to.
kind"fiat" | "crypto"Same discriminator as the account itself.
currencystringThe account's currency. Both amounts are denominated in it.
balancestringTotal funds credited to the account, in major units.
available_balancestring?The portion spendable right now (total minus holds and pending credits). Omitted when the distinction doesn't exist for the account.
as_oftimestampWhen Seismic last refreshed the balance.

Amounts are decimal strings in major units, like every other amount on the API.

Example

{
  "account_id": "5e3a…",
  "kind": "fiat",
  "currency": "GBP",
  "balance": "150.00",
  "available_balance": "130.00",
  "as_of": "2026-06-12T12:30:00Z"
}

Errors

  • 400: the account is origin: "external". Balance only exists for virtual accounts.
  • 404: unknown id, or the account belongs to a different org.
  • 503: the account has never been synced and the backfill read couldn't complete right now. Retry with backoff.

Example

curl "$SEISMIC_ORCHESTRATION_URL/v0/accounts/5e3a…/balance" \
  -H "Api-Key: $SEISMIC_ORCHESTRATION_API_KEY"

Reconciling against deposits

balance is the current state. GET /deposits is the history that produced it. A deposit that has been received but not yet settled shows up in the deposit list (status pending or under_review) before it moves available_balance. To reconcile, sum the completed deposits credited to the account, subtract the refunded ones, and compare against balance.