Overview
Read available, reserved, and total balances for each currency/network pair.
GET /v1/balances returns one row for each balance pair in the API key's environment. It requires balances:read and has no pagination or filter parameters.
Balance fields#
| Field | Meaning |
|---|---|
currency | Asset code |
network | Network key |
available | Funds currently available to spend |
reserved | Funds committed to outgoing payouts and refunds |
total | available plus reserved |
All amounts are decimal strings. Do not sum different currency/network pairs as if they shared a denomination. The same ticker on two networks identifies two balances.
When balances change#
Observed or unconfirmed deposits do not enter the spendable balance before acceptance. Creating an outgoing operation reserves its merchant debit; successful execution finalizes the outgoing movement. A failed or reversed operation can release or restore funds according to its lifecycle.
Invoice amount_paid is accepted gross, not a net balance. Fees, refunds, conversions, and other movements mean invoice turnover is not interchangeable with available funds.
Reconciliation#
Keep a local registry of resource IDs, process webhooks idempotently, and fetch the current object before acting on its status. Read balances to check current funds.
Detailed transaction history, ledger entries, lifetime turnover, and USD portfolio totals belong in the dashboard. The merchant API does not expose /v1/transactions or a transaction-detail endpoint.