#Balances & deposits

Read spendable balances and incoming deposit history

2 endpoints. Generated from docs/openapi.yaml v1.0.0.

Endpoint	Summary
`GET /v1/users/{externalId}/balances`	Get a user's spendable balances
`GET /v1/users/{externalId}/deposits`	List a user's deposits

#GET/v1/users/{externalId}/balances

Get a user's spendable balances · Auth: bearer API key · operationId: getUserBalances

Spendable, always net of holds. A pending withdrawal places its hold at REQUEST time — the held amount (plus fees) leaves the user's balance immediately and sits in a pending account until the operation confirms or is refunded.

The guarantee runs in one direction and is safe to rely on: while an operation is in flight this endpoint reads lower than the user's eventual balance, never higher. It cannot report a surplus that a queued payout is about to consume. If the operation fails, the hold is reversed and the balance returns.

Assets with no activity are absent from the response. So is an empty account on a chain the platform no longer serves (Chain) — a user from before a chain was retired keeps such rows, and they are listed only while they hold a balance.

on_chain is what the user's own address holds at this moment, for comparison with a block explorer. It is not the spendable figure and the two differ by design (see the Balance schema).

#Parameters

Name	In	Type	Required	Description
`externalId`	path	`string`	yes	Your `external_user_id` for the user.

#Responses

Status	Body	Meaning
`200`	`object[]`	Per-asset balances.
`401`	`Error`	Missing, malformed or unknown API key.
`404`	`Error`	Unknown externaluserid for this tenant.

200 response body

Field	Type	Description
`[].asset_id` required	`string`	—
`[].symbol` required	`string`	—
`[].chain` required	`string`	The chain an address or asset is on. TRON is the only network the platform serves: `btc`, `eth`, `bsc` and `sol` were retired — historical addresses on them are never handed out again and nothing scans them. Read the value as an open string rather than a closed list, so a chain added later does not break your client. (one of `tron`)
`[].amount` required	`string`	A monetary value as a decimal string. Always paired with a `*_base` field that carries the exact integer base-unit value; compute with the `_base` string.
`[].amount_base` required	`string`	Exact integer amount in the asset's smallest unit. (pattern `^[0-9]+$`)
`[].on_chain` required	`string`	What the user's own deposit address holds right now, read live from the chain. Informational: `amount` is the balance the platform enforces. The two differ by design — fees leave the address for the platform's profit wallet as they settle, earnings (commission, a merchant's own fees) are credited from there, and a balance from before 4 September 2026 lives in the platform's wallets. `null` when the address could not be read in time.
`[].on_chain_base` required	`string`	Exact integer amount in the asset's smallest unit. (pattern `^[0-9]+$`)

json

[
  {
    "asset_id": "usdt_trc20",
    "symbol": "USDT",
    "chain": "tron",
    "amount": "1.5",
    "amount_base": "1500000000",
    "on_chain": "1.5",
    "on_chain_base": "1500000000"
  }
]

#Example request

bash

curl -X GET 'https://api.cryptoinfra.build/v1/users/string/balances' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/users/{externalId}/deposits

List a user's deposits · Auth: bearer API key · operationId: getUserDeposits

Most recent deposits first.

The optional range filters on when the deposit was FIRST SEEN on-chain, not on when it was credited — so a still-pending deposit cannot fall out of a window that covers it. from/to accept either a bare IST calendar day (YYYY-MM-DD, both ends included) or a full RFC 3339 instant with an offset.