API reference

Balance

What your settlement wallet actually holds, read live from the chain.

What this reads

The live on-chain balance of your settlement wallet on EVM networks, across the configured tokens. The wallet is resolved from your merchant config server-side and the merchant comes from your API key, so there is nothing to pass. Read-only.

Balances are read from the chain on every call (ERC-20 balanceOf), which means they depend on an RPC endpoint being configured. One token failing shows up as a per-entry error inside an otherwise normal 200; no RPC at all for the network fails the whole request with 503.

Each entry also carries the token's decimals — the source of truth for converting base units on that network. Because it moves nothing, this is also the endpoint the smoke test calls.

You do not need it before a payout: creating one checks your payout wallet's balance and allowance itself and answers insufficient_funds or insufficient_allowance with the numbers.

Balance

Live on-chain balances of your settlement wallet.

GET /v1/balance signed

Read settlement wallet balances

Live ERC-20 balanceOf reads across your configured tokens. Signed like any other request: the canonical string uses GET, the path, and the hash of an empty body.

Request

curl -X GET "$BASE_URL/v1/balance" \
  -H "X-Api-Key: $API_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIG"

res, err := client.Call(ctx, "GET", "/v1/balance", "")

$res = $client->call('GET', '/v1/balance');

const res = await client.call("GET", "/v1/balance");

res = client.call("GET", "/v1/balance")

const res = await client.call("GET", "/v1/balance");

The client is the one on Signing requests: it signs, sends, and turns an error into an exception carrying its code.

Response 200

Live balances. A token whose read failed carries error instead of amount.

{
  "wallet": "0x2222222222222222222222222222222222222222",
  "balances": [
    {
      "network": "eth",
      "token": "USDT",
      "address": "0xdAC1…",
      "decimals": 6,
      "amount": "1250.5",
      "raw": "1250500000"
    },
    {
      "network": "eth",
      "token": "USDC",
      "address": "0xA0b8…",
      "decimals": 6,
      "amount": "0",
      "raw": "0"
    }
  ]
}

Errors

401 unauthorized The signature, key, timestamp or nonce did not check out: a missing header, an unknown key id, a timestamp more than 5 minutes from ours, a signature that does not match, or a nonce already used inside the window. Do not retry without rebuilding the request — a retry needs a new timestamp, a new nonce and a new signature.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid signature"
  }
}

403 forbidden The credential is valid but the caller's IP is not in the allowlist configured for your merchant. Not retryable.

{
  "error": {
    "code": "forbidden",
    "message": "client IP not allowed for this merchant"
  }
}

503 unavailable No RPC endpoint is configured for the network, so no balance can be read at all. Unlike a single token failing — which shows up as a per-entry error inside a 200 — this fails the whole request.

{
  "error": {
    "code": "unavailable",
    "message": "no RPC for network \"eth\""
  }
}