API ReferenceBalances

Check a balance

View as MarkdownOpen in Claude

The balance of the user’s wallet for that asset, as a human-decimal string — never a float, never base units.

Dust is floored to "0": below 0.00001 for a native coin (0.0001 for BTC), and below 0.0001 for a token. A "0" balance therefore does not prove the address is empty.

Authentication

AuthorizationBearer

A 15-minute token from /auth. Required on every endpoint except /auth.

Headers

X-Request-IdstringOptional
Correlation id. Generated if omitted, echoed on every response, and written to the audit log.
X-USER-IDstringOptionalformat: "^[0-9a-fA-F]{24}$"

Sent by the trusted gateway. When present it overrides any userId in the body.

Request

This endpoint expects an object.
userIdstringRequiredformat: "^[0-9a-fA-F]{24}$"

24-character hex id, returned by /create.

assetIdenumRequired
Primary asset selector. An all-digit string (`"21"`) is accepted and normalised to an integer. - `1` — BITCOIN BTC (native, 8 decimals) - `2` — ETHEREUM ETH (native, 18 decimals) - `21` — ETHEREUM USDT (ERC20, 6 decimals) - `22` — ETHEREUM USDC (ERC20, 6 decimals) - `3` — BNB BNB (native, 18 decimals) - `31` — BNB USDT (BEP20, 18 decimals) - `32` — BNB USDC (BEP20, 18 decimals) - `4` — TRON TRX (native, 6 decimals) - `41` — TRON USDT (TRC20, 6 decimals) - `42` — TRON USDC (TRC20, 6 decimals) - `5` — POLYGON POL (native, 18 decimals) - `51` — POLYGON USDT (ERC20, 6 decimals) — mainnet only - `52` — POLYGON USDC (ERC20, 6 decimals) - `6` — SOLANA SOL (native, 9 decimals) - `61` — SOLANA USDT (SPL, 6 decimals) — mainnet only - `62` — SOLANA USDC (SPL, 6 decimals)

Response

OK
resultstringformat: "^\d+(\.\d+)?$"

Balance in the asset, as a human-decimal string. Dust is floored to "0".

requestIdstring

Echo of the inbound X-Request-Id, or a generated one.

Errors

400
Bad Request Error
401
Unauthorized Error
503
Service Unavailable Error