Balances

Details about where a customer's money sits.

Balances live on the customer. The virtual account that received the money does not hold one, and neither does the deposit address. Your own account holds balances as well, which you read with GET /v1/balances. See Your own balances.

GET /v1/customers/{customerId}/balances

A balance grows when a deposit is credited. In sandbox nothing is provisioned for you and you cannot transfer funds in, so the way to put money on a customer is to simulate a deposit. See Testing in sandbox.

Four classes, plus a total

ClassMeans
availableSpendable funds. This is the only class you can act on.
pendingFunds have arrived but have not settled yet.
heldSettled but locked, usually against something in flight.
blockedA control has restricted these funds.
totalThe sum of the classes above. Use it for display. It won't tell you whether a payment will go through.

Internal ledger classes never appear here. These values are what the customer actually holds.

Check available before every execution. A payout or conversion against any other class fails with insufficient_balance. That is a 422, and retrying it will not make it succeed.

What a balance can be

Each entry carries a scope.type:

  • stablecoin_balance is held in USDC or USDT and carries a chain.
  • local_stablecoin covers MXNa, ARSa, COPa and BRZ.

A customer can hold several at once. Filter with ?type= when you only care about one kind.

Your own balances

GET /v1/balances

Your own account holds balances too, and this call reads them. It takes no customerId, because your API key identifies the account. This is the balance that funds payouts from your own account. See Paying out.

{
  "data": [
    {
      "scope": { "type": "stablecoin_balance", "id": null },
      "asset": "USDC",
      "chain": "SOL",
      "currency": "USD",
      "available": "5000.00",
      "pending": "0.00",
      "held": "0.00",
      "blocked": "0.00",
      "total": "5000.00"
    },
    {
      "scope": { "type": "local_stablecoin", "id": null },
      "asset": "ARSa",
      "chain": null,
      "currency": "ARS",
      "available": "2500.00",
      "pending": "0.00",
      "held": "0.00",
      "blocked": "0.00",
      "total": "2500.00"
    }
  ]
}

There is one row per balance. Each row carries the same four classes and total as a customer's balance, and the same rule applies: only available can be spent.

FieldWhat it is
scope.typestablecoin_balance or local_stablecoin
assetWhat is held, such as USDC, USD or ARSa
chainThe chain for an on-chain asset, and null otherwise
currencyThe currency the balance is denominated in

The availability rule

Money being received and money being spendable are two different moments.

A deposit reaching PROCESSING with FUNDS_HELD means the conversion confirmed and the controls cleared. The funds still aren't spendable at that point. settlement_status reaches SETTLED and the balance becomes available only once delivery to the vault is confirmed as well.

Don't release anything on an intermediate status. Wait for deposit.credited and then read available.

Reconciling

Two reads cover reconciliation, and each one answers a different question.

The journal records every movement.

GET /v1/customers/{customerId}/balance_transactions

Every flow posts into it. Each entry carries source back to the deposit, conversion or payout that created it, so you can reconcile against your own records.

Assets under management cover the whole book.

GET /v1/aum?scope=&type=

This returns totals across everything under your key. There's no customer parameter and no partner parameter, because your key defines the book. scope takes sub_customers, self or all.

You can rely on per-customer balance reads at the same asOf summing exactly to this figure.


Did this page help you?