Wallet & Deposits

Your workspace wallet is the prepaid balance every order spends from. This page covers reading the balance, funding it with on-chain BSC-USD, and auditing the deposit history. Reads require wallet.read; requesting the deposit address requires the dedicated wallet.deposit-address.write scope.

Read the balance

GET /api/v1/wallet/balance?currency=USD

{
  "availableBalance": 425.00,
  "reservedBalance": 75.00,
  "currency": "USD",
  "asOfUtc": "2026-09-05T12:00:00Z"
}

• availableBalance — spendable right now (new orders draw from this).
• reservedBalance — held by in-flight orders; released on failure/cancellation, captured on fulfillment.

Alert your operations well before available funds reach your hourly burn rate — an order admitted without sufficient funds is rejected, not queued.

Fund with BSC-USD

Funding is on-chain: your workspace gets a permanent, dedicated deposit address for BSC-USD (the BEP-20 stable token on BNB Smart Chain, chain id 56). Anything confirmed at that address is credited to your wallet automatically — no deposit "intents", no amounts to pre-declare.

Request (or fetch) the address

PUT /api/v1/wallet/deposit-addresses/bsc-usd     (scope: wallet.deposit-address.write)
GET /api/v1/wallet/deposit-addresses/bsc-usd     (scope: wallet.read)

PUT is idempotent: the first call starts allocation and returns 202 Accepted; every later call returns 200 OK with the same account ("replayed": true). GET returns 404 until a PUT has been made.

{
  "id": "0198db4d-f20c-765e-a89a-2b1b0b9a4f74",
  "chainId": 56,
  "assetCode": "USDT",
  "tokenAddress": "0x55d398326f99059fF775485246999027B3197955",
  "tokenDecimals": 18,
  "requiredConfirmations": 15,
  "ledgerCurrency": "USD",
  "status": "Active",
  "depositAddress": "0x1111111111111111111111111111111111111111",
  "cumulativeConfirmedRaw": "12500000000000000000",
  "pendingRawRemainder": "500000000000000000",
  "requestedAtUtc": "2026-09-05T11:59:00Z",
  "activatedAtUtc": "2026-09-05T12:00:00Z",
  "replayed": true
}

Reading the response correctly:

• depositAddress is null until status is Active. Allocation is asynchronous (usually under a minute) — poll GET until the address appears, and never display a non-Active account to your treasury team.
• Verify the token, not just the address. Send only the token at tokenAddress on chain chainId. Any other asset or network sent to the address cannot be credited.
• Raw amounts are strings in the token's smallest unit (tokenDecimals, here 18) so no precision is lost. cumulativeConfirmedRaw is everything ever confirmed; pendingRawRemainder is dust below the ledger's credit granularity that carries over.
• The address is permanent and reusable — print it into your treasury runbook once; deposits any time simply appear.

How crediting works

1. Your transfer is observed on-chain (status: Observed).
2. It matures for requiredConfirmations blocks (Confirming).
3. It is credited to your wallet at 1 token unit = 1 ledgerCurrency unit (Credited), and a wallet.credited webhook fires with the new available balance.

Audit the deposit history

GET /api/v1/wallet/deposits?limit=50
GET /api/v1/wallet/deposits?afterObservedAtUtc=2026-09-05T12:00:00Z&afterId=0198db4d-f2d9-7f8d-867d-329b081134a3&limit=50

Keyset-paginated, oldest-first: pass back the previous response's nextObservedAtUtc + nextId together (both or neither; limit 1–100) to continue.

{
  "items": [
    {
      "id": "0198db4d-f2d9-7f8d-867d-329b081134a3",
      "depositAccountId": "0198db4d-f20c-765e-a89a-2b1b0b9a4f74",
      "transactionHash": "0x2222…",
      "logIndex": 1,
      "blockNumber": 42000000,
      "amountRaw": "12500000000000000000",
      "ledgerAmount": 12.50,
      "ledgerCurrency": "USD",
      "status": "Credited",
      "confirmationCount": 15,
      "observedAtUtc": "2026-09-05T12:00:00Z",
      "confirmedAtUtc": "2026-09-05T12:01:00Z",
      "creditedAtUtc": "2026-09-05T12:02:00Z"
    }
  ],
  "nextObservedAtUtc": null,
  "nextId": null
}

ledgerAmount is null until the deposit is credited. Each row is uniquely identified by transactionHash + logIndex, so reconciling against your own chain records is exact.

Treasury reconciliation loop

A robust daily loop:

1. Walk GET /wallet/deposits from your last stored cursor; match each row to your outgoing transfers by transactionHash.
2. Compare GET /wallet/balance with your ledger (deposits − captured orders − withdrawals).
3. Investigate any deposit stuck in Observed/Confirming far beyond the confirmation window with support, quoting the deposit id and transactionHash.