Balances

Current balances and historical balances

GET /v2/balances

List the account asset balances

Amounts are in the underlying equity for tokenised assets by default; pass assetFormat=base for the settled SPV quantities that moved on chain and in the ledger. Every response echoes assetFormat and multiplier, so the units are never implicit.

Parámetros

Parámetro	En	Tipo	Requerido	Descripción
assetFormat	query	AssetFormat	no	How to express tokenised-equity (xStock) amounts. rebased (default) = underlying equity (real shares); base = settled SPV tokens, i.e. what is held on chain and in the ledger. No effect on other assets.

Respuestas

Código	Descripción	Cuerpo
200	Éxito.	object
401	application/problem+json (RFC 9457) — branch on code, not on the status: unauthorized (not retryable), key_expired (not retryable), key_revoked (not retryable).	—
403	application/problem+json (RFC 9457) — branch on code, not on the status: insufficient_scope (not retryable), ip_not_allowed (not retryable), api_access_disabled (not retryable).	—
429	application/problem+json (RFC 9457) — branch on code, not on the status: rate_limited (retryable).	—
500	application/problem+json (RFC 9457) — branch on code, not on the status: internal_error (retryable).	—
502	application/problem+json (RFC 9457) — branch on code, not on the status: downstream_unavailable (retryable).	—
503	application/problem+json (RFC 9457) — branch on code, not on the status: maintenance (retryable).	—

---

GET /v2/balances/{assetSymbol}/history

Historical balances for an asset

End-of-period balance for one asset, at day, week or month granularity.

Amounts are SETTLED quantities and this endpoint takes no assetFormat. The points carry no per-point rebase factor, so expressing them as the underlying equity would mean applying TODAY's ratio to past history — after a 10:1 split every earlier point would appear to jump tenfold. A correct unscaled series beats a scaled and possibly false one.

assetSymbol still accepts either spelling: NVDAX reads the same series as NVDASPV, because that only selects which asset to read, never how it is expressed. The response echoes the settled code, so the label always matches the units.

Parámetros

Parámetro	En	Tipo	Requerido	Descripción
assetSymbol	path	string	sí	The asset code published as assetSymbol by GET /v2/assets. For a tokenised equity the rebased ticker also resolves — NVDAX reads the same series as NVDASPV.
page	query	integer	no	Default: 1.
limit	query	integer	no	Default: 25.
startDate	query	string	no	ISO-8601 start date. Defaults to the first movement.
endDate	query	string	no	ISO-8601 end date. Defaults to now.
granularity	query	day | week | month	no	Default: day.

Respuestas

Código	Descripción	Cuerpo
200	Éxito.	HistoricalBalancesResponse
401	application/problem+json (RFC 9457) — branch on code, not on the status: unauthorized (not retryable), key_expired (not retryable), key_revoked (not retryable).	—
403	application/problem+json (RFC 9457) — branch on code, not on the status: insufficient_scope (not retryable), ip_not_allowed (not retryable), api_access_disabled (not retryable).	—
404	application/problem+json (RFC 9457) — branch on code, not on the status: not_found (not retryable).	—
429	application/problem+json (RFC 9457) — branch on code, not on the status: rate_limited (retryable).	—
500	application/problem+json (RFC 9457) — branch on code, not on the status: internal_error (retryable).	—
502	application/problem+json (RFC 9457) — branch on code, not on the status: downstream_unavailable (retryable).	—
503	application/problem+json (RFC 9457) — branch on code, not on the status: maintenance (retryable).	—

---

Esquemas

BalanceBaseRepresentation

Campo	Tipo	Descripción
asset	string	Asset code of the settled token — the SPV code for a tokenised equity, and the ordinary code otherwise. Always present. Ej.: NVDASPV.
balance	string	Balance in settled units. Ej.: 10.
balanceFrozen	string	Frozen balance in settled units. Ej.: 0.
balancePending	string	Pending balance in settled units. Ej.: 0.

BalanceResource

Campo	Tipo	Descripción
assetSymbol	string	The asset, named in the representation the amounts below are in — the rebased ticker on a rebased read of a tokenised equity, the settled code otherwise. Ej.: NVDAX.
balance	string	Ej.: 10.5.
balanceFrozen	string	Ej.: 0.
balancePending	string	Ej.: 0.
balancePrefCurrency	string	This balance converted to the account's preferred currency. The unit is not repeated here — read preferredCurrency from GET /v2/account. Named for its unit, like balanceUSD. Ej.: 1837.50.
balanceUSD	string	Ej.: 1837.50.
balanceCapacityTotal (opcional)	string	Ej.: 5000.
balanceCapacityAvailable (opcional)	string	Ej.: 5000.
balanceCapacitySpent (opcional)	string	Ej.: 0.
multiplier	string	This asset's rebase factor as it stands NOW, published whether or not it was applied — so a client can convert between the two representations without a second read. "1" when the asset does not rebase. On a rebased read divide an amount by it to recover the settled (SPV) figure; on a base read multiply. Unlike an order or a fill — whose factor is the one stamped when they settled — a balance is a current holding, so the current factor is the correct one. Ej.: 1.05.
assetFormat	any	Which representation the amounts and assetSymbol above are in — the value you asked for, or the default. Always present, so a client never has to infer the units it was given. Ej.: rebased.
base	any	The same holding in SETTLED units — what is held on chain and in the ledger. Present in BOTH representations, so a client reconciling against a webhook or a ledger entry never has to re-read with a different assetFormat. On a base read it repeats the figures above rather than disappearing, which is what keeps the shape stable.

HistoricalBalancePoint

Campo	Tipo	Descripción
date	string
balance	string	Balance at the end of the period, as an exact decimal string in plain notation — never exponential. Truncated to the asset operating precision. Parse it as a decimal, not a float. For a tokenised equity this is the SETTLED quantity: see the note on assetSymbol for why this one series is not offered in the rebased representation. Ej.: 500.62.

HistoricalBalancesResponse

Campo	Tipo	Descripción
assetSymbol	string	The SETTLED asset code, echoed regardless of which spelling the request used — a tokenised equity is named by its SPV code here because the balances below are settled quantities. This series carries no assetFormat and is never rebased: the points have no per-point factor, so scaling them would apply today's ratio to past history. Ej.: BTC.
granularity	day | week | month
startDate	string | null
endDate	string | null
data	HistoricalBalancePoint[]
pagination	PaginationMeta

PaginationMeta

Campo	Tipo	Descripción
page	number	Ej.: 1.
limit	number	Ej.: 25.
totalItems	number	Ej.: 100.
totalPages	number	Ej.: 4.

Problem

Campo	Tipo	Descripción
type	string	Stable problem-type URI. Resolves to docs for this error. Ej.: https://docs.skipo.com/errors/rate_limited.
title	string	Short, human-readable summary (stable, English). Ej.: Rate limit exceeded.
status	number	HTTP status code. Ej.: 429.
code	string	Stable machine-readable error code (equals the last path segment of type). Ej.: rate_limited.
retryable	boolean	Whether retrying the identical request may succeed. Ej.: true.
detail (opcional)	string	Human-readable, possibly localized detail.
instance (opcional)	string	The request path that produced the error.
traceId (opcional)	string	Trace id — joins BigQuery api_request and Cloud Logging.

---

Volver a la referencia de endpoints. Ver también: Paginación · Errores · Ids y correlación.