Skip to main content

Get Balances

GET /merchant/settlements/balances returns your cashout-able balance per asset — matured funds only — plus a "maturing" bucket for funds still inside the settlement waiting window. Call it before creating a settlement to know how much you can withdraw now.

Example​

TS=$(date +%s); BODY=""
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | awk '{print $2}')
curl https://api-staging.finomesh.com/api/v1/merchant/settlements/balances \
  -H "X-Api-Key: $FINOMESH_API_KEY" \
  -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Each item carries assetId, symbol, networkId, totalAvailable (a decimal string — the amount you can withdraw now), totalAvailableUsd, and the maturing totalPending* fields.

The totalAvailable figure is the ceiling for a create settlement amount on that asset. Asking for more is not automatically an error — it either parks the cashout or returns 409 insufficient_balance, depending on your gateway (details).

There is no "withdraw everything" request shape: read totalAvailable here and pass it as amount.

Held (AML) balance​

On AML-screened gateways each item also reports a second pool, totalQuarantinedAvailable (+ totalQuarantinedAvailableUsd, quarantinedPayments, and the maturing totalQuarantinedPendingAvailable): deposits our screening flagged. They are excluded from totalAvailable and are withdrawn by naming that pool on the cashout — route: "AML_HELD", in exact amounts just like the green pool, with totalQuarantinedAvailable as its ceiling. On gateways without screening these figures are always 0. To see which payments are held, check amlState on verify.

Reference​