# Balances (/reference/balances)

## A customer's balance per asset

`GET /v1/customers/{id}/balances`

The read most integrations want. `available` is spendable; `locked` is reserved against an in-flight payout.

### Parameters

- `id` (path, required, string (uuid))

### Responses

- `200` — Balances.
  - `object` (optional, string)
  - `customer_id` (optional, string (uuid))
  - `data` (optional, array)
    - `asset` (required, object)
      - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
      - `symbol` (required, string)
      - `decimals` (required, integer) — Authoritative scale for this asset ON THIS CHAIN. USDT and USDC are 18 on BSC and 6 everywhere else — never hardcode 6.
      - `contract` (optional, string | null) — null for the chain's native coin.
      - `logo_url` (optional, string | null) — The coin's logo, served from MolnPay's own CDN (assets.molnpay.com) — not a third party, so it is safe to render on a payment page. Decoration: it can 404 for a coin whose art we have not uploaded yet, and it is the same art our own console renders — build a picker on it rather than maintaining your own symbol-to-logo map, but never block a render on it. Sizes are 32, 64 and 128; the URL gives 64.
    - `available` (required, string) — Spendable balance, atomic units.
    - `available_decimal` (required, string)
    - `locked` (required, string) — Reserved against an in-flight payout.
    - `locked_decimal` (optional, string)
    - `total` (required, string) — available + locked.
    - `total_decimal` (optional, string)
    - `onchain` (optional, string) — Live on-chain balance. Only for source=chain|both.
    - `onchain_decimal` (optional, string)
    - `drift` (optional, string) — onchain − total. Non-zero is normal transiently (unconfirmed deposits, in-flight sweeps); a persistent non-zero is worth investigating.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## GET /v1/wallets/{id}/balances

`GET /v1/wallets/{id}/balances`

### Parameters

- `id` (path, required, string (uuid))
- `source` (query, optional, string, one of: ledger, chain, both) — `chain` and `both` include the on-chain reading and a `drift` field, and are rate-limited harder.

### Responses

- `200` — Balances.
  - `object` (optional, string)
  - `wallet_id` (optional, string (uuid))
  - `source` (optional, string)
  - `data` (optional, array)
    - `asset` (required, object)
      - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
      - `symbol` (required, string)
      - `decimals` (required, integer) — Authoritative scale for this asset ON THIS CHAIN. USDT and USDC are 18 on BSC and 6 everywhere else — never hardcode 6.
      - `contract` (optional, string | null) — null for the chain's native coin.
      - `logo_url` (optional, string | null) — The coin's logo, served from MolnPay's own CDN (assets.molnpay.com) — not a third party, so it is safe to render on a payment page. Decoration: it can 404 for a coin whose art we have not uploaded yet, and it is the same art our own console renders — build a picker on it rather than maintaining your own symbol-to-logo map, but never block a render on it. Sizes are 32, 64 and 128; the URL gives 64.
    - `available` (required, string) — Spendable balance, atomic units.
    - `available_decimal` (required, string)
    - `locked` (required, string) — Reserved against an in-flight payout.
    - `locked_decimal` (optional, string)
    - `total` (required, string) — available + locked.
    - `total_decimal` (optional, string)
    - `onchain` (optional, string) — Live on-chain balance. Only for source=chain|both.
    - `onchain_decimal` (optional, string)
    - `drift` (optional, string) — onchain − total. Non-zero is normal transiently (unconfirmed deposits, in-flight sweeps); a persistent non-zero is worth investigating.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — Not found.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Project-wide solvency per asset

`GET /v1/balances`

`surplus` is assets minus liabilities. A negative value means more is owed to customers than is held — the single most important number this service produces.

### Responses

- `200` — Treasury.
  - `object` (optional, string)
  - `data` (optional, array)
    - `asset` (optional, object)
      - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
      - `symbol` (required, string)
      - `decimals` (required, integer) — Authoritative scale for this asset ON THIS CHAIN. USDT and USDC are 18 on BSC and 6 everywhere else — never hardcode 6.
      - `contract` (optional, string | null) — null for the chain's native coin.
      - `logo_url` (optional, string | null) — The coin's logo, served from MolnPay's own CDN (assets.molnpay.com) — not a third party, so it is safe to render on a payment page. Decoration: it can 404 for a coin whose art we have not uploaded yet, and it is the same art our own console renders — build a picker on it rather than maintaining your own symbol-to-logo map, but never block a render on it. Sizes are 32, 64 and 128; the URL gives 64.
    - `deposits` (optional, string) — Held on customer deposit addresses.
    - `treasury` (optional, string) — Held in your master wallet.
    - `in_transit` (optional, string) — Broadcast but not yet confirmed.
    - `held_in_custody` (optional, string) — Held for you in MolnPay's own custody rather than in a wallet of yours: payments received at pooled invoice addresses. Counted as an asset.
    - `liability` (optional, string) — Total owed to customers (available + locked).
    - `surplus` (optional, string) — assets − liabilities. NEGATIVE means more is owed to customers than is held. Alarm on this.
    - `value_usd_cents` (optional, string | null) — Report-only USD value of everything held on this line, in whole cents, at spot when the request was served. `null` when the coin has no usable price right now — never `"0"` for that case. The list is returned in this order, largest first, so the first rows are the biggest positions rather than the alphabetically first chains.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.