Balances and withdrawals¶

Money that has been swept out of an invoice or a static wallet lands on your balance, less the merchant fee and the network fee of moving it. Withdrawing moves it from there to an address you name.

Balances¶

curl https://api.pay.nullswap.com/api/v1/merchant/balances \
  -H "x-api-key: sk_live_..."

{
  "items": [
    {
      "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "currency": "USDT",
      "decimals": 6,
      "amount": "125000000",
      "balanceId": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c"
    }
  ]
}

Note the envelope: { "items": [...] }, not the { "data": [...], "pagination": {...} } used elsewhere. There is no pagination and there are no filters — you get every row you have.

One row is one token. A token you have never been paid in is normally absent rather than zero, but a row can also read "0" — after you have withdrawn everything, for example — so treat an absent row and "0" alike. A balance in a token that is no longer listed in /api/v1/tokens is not reported.

The whole of amount is yours to withdraw. Only money that has confirmed and cleared screening is ever swept onto your balance; funds that failed screening never reach it and stay on the deposit or static address they arrived on. Read them per payment, through amlStatus on invoice payments and settlement: WITHHELD on static wallet payments.

amount is a base-unit integer as a string; divide by 10^decimals to display it. As always, only sum amounts within one tokenId — see conventions.

The merchant fee¶

We charge each merchant a fee on its payments: a rate in basis points, shown as feePercentage on GET /api/v1/merchant. We set it, and an API key can never change it. The fee is withheld when a sweep settles onto your balance: of what arrived, the fee is kept and your balance is credited the rest.

fee      = floor(amount × feePercentage / 10000)
credited = amount − fee − network fee

amount is what the sweep delivered, in base units of the token it was credited in. The fee is rounded down to a whole base unit, so a rounding remainder always stays with you. At "0" nothing is withheld for the merchant fee.

The network fee is the cost of moving the money on a token sweep, valued in the credited token and withheld next to the merchant fee. It is zero on a sweep of a chain's native coin, on UTXO chains and on Monero, where the sweep pays its own way out of what it moves. It has no field of its own: it is the difference between amount − fee and credited.

Each sweep fixes its rate when it is opened. A rate change applies to sweeps opened after it, never to one already on its way.

The withdrawal fee is a separate charge, taken when you withdraw. Your balances are already net of every merchant fee and sweep network fee.

List the fees withheld¶

curl "https://api.pay.nullswap.com/api/v1/merchant/fees?settledFrom=2026-01-01T00:00:00.000Z&settledTo=2026-02-01T00:00:00.000Z&limit=50" \
  -H "x-api-key: sk_live_..."

{
  "data": [
    {
      "id": "0b1c2d3e-4f50-4617-8a29-3b4c5d6e7f80",
      "merchantId": "9f1d2c3b-4a5e-4f60-8b71-2c3d4e5f6a7b",
      "walletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
      "invoiceId": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
      "staticWalletId": null,
      "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "transferRequestId": "4d5e6f70-8192-4a3b-9c4d-5e6f708192a3",
      "amount": "25500000",
      "credited": "25117500",
      "fee": "382500",
      "feePercentage": "150",
      "feeUsd": "382576500000000000",
      "settledAt": "2026-01-01T12:14:00.000Z",
      "creditedTokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "dstTokenId": null,
      "amountIn": null,
      "amountOut": null,
      "conversionSkipReason": null
    }
  ],
  "pagination": { "offset": 0, "limit": 50, "total": 1, "order": "DESC" }
}

One row is one settled sweep. Every sweep that settled onto your balance since the merchant fee was introduced is listed, a sweep at a zero rate included with fee: "0"; sweeps still on their way are not.

feeUsd is for reporting only. A fee whose token had no price at settlement reads null and is priced later, at the price of that later moment. Sum fee per tokenId for exact figures — see conventions.

Raising a withdrawal¶

curl -X POST https://api.pay.nullswap.com/api/v1/merchant/withdrawals \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
    "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
    "to": "0xfedcba0987654321fedcba0987654321fedcba09",
    "amount": "50000000",
    "externalId": "payout-2026-01-14-001"
  }'

{
  "transferRequestId": "9c0d1e2f-3a4b-45c6-8d78-9e0f1a2b3c4d",
  "status": "PENDING",
  "hash": null,
  "amount": "50000000",
  "fee": "1350000"
}

201 means accepted for processing, not sent. Nothing has touched the chain yet, hash is null, and the outcome arrives asynchronously. What has happened is the debit: the amount and the fee are taken off your balance when the withdrawal is accepted, and a withdrawal your balance does not cover is refused there and then with 422 INSUFFICIENT_MERCHANT_BALANCE.

Two checks do run on to before anything is debited:

• Screening. The destination is screened when the withdrawal is placed. An address that fails is refused with 422 RECIPIENT_ADDRESS_BLOCKED; SKIPPED lets the withdrawal through. Monero destinations are not screened.
• Your withdrawal whitelist, if you turned it on. The merchant's owner can restrict payouts to a list of trusted addresses in the cabinet, under Settings → Whitelists. With the restriction on, a to that is not on the list for that chain is refused with 422 WITHDRAWAL_ADDRESS_NOT_WHITELISTED — API calls included — and with the list empty every payout is refused. The list is per chain: an address added for one EVM network is not trusted on another. On RIPPLE an entry is an address and a destination tag together, and a payout matches only the entry with exactly its toTag — an entry without a tag matches only a payout without one.

Withdrawing to RIPPLE¶

On RIPPLE, the XRP Ledger, most exchanges and custodians receive on one account shared by all their customers and tell them apart by a destination tag. Send the recipient's tag as toTag, or send the X-address they gave you as to. A payout to such an account without the tag reaches the exchange and nobody's balance there.

Two more checks read the recipient's account off the ledger before anything is debited:

• A required tag. An account that refuses payments without a destination tag, paid with no toTag, is refused with 422 DESTINATION_TAG_REQUIRED.
• An account that does not exist yet. An XRP Ledger account is created by its first payment, and only if that payment is at least the network's base reserve — currently 1 XRP. A payout to an account that does not exist, for less than that, is refused with 422 DESTINATION_NOT_ACTIVATED, and details.minAmount says how much it takes, in drops:

{
  "statusCode": 422,
  "message": "DESTINATION_NOT_ACTIVATED",
  "timestamp": "2026-01-14T09:00:00.000Z",
  "details": {
    "minAmount": "1000000"
  }
}

Read the figure from details.minAmount rather than hard-coding it: the reserve is the network's to change. Neither refusal debits anything, and the same externalId can be sent again once the request is fixed.

The fee¶

A withdrawal costs the network fee of sending it, and you pay it in the token you withdraw, converted at that token's current price, with a small margin for movement between the estimate and the send. fee in the response is what you were charged and amount is what the recipient is sent, both in base units of tokenId. There are no other charges, and no gas to keep on hand: you never need a balance in the chain's native coin to withdraw a token.

true is how you withdraw everything: send your whole balance as amount and the fee comes out of it. With false, withdrawing your whole balance is refused for want of the fee.

The fee is priced again at the moment of the withdrawal, so it can differ from any estimate you were shown. Pass maxFee to cap it: a withdrawal whose fee comes out higher is refused with 422 FEE_EXCEEDS_MAX_FEE, and nothing is debited.

Quote the fee¶

curl "https://api.pay.nullswap.com/api/v1/merchant/withdrawals/fee-quote?chainId=1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10&tokenId=3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908" \
  -H "x-api-key: sk_live_..."

{
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "nativeTokenId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "nativeFee": "2800000",
  "fee": "1350000"
}

fee is what a withdrawal of tokenId would be charged right now, in its base units, margin included. nativeFee is the network cost it was converted from, in base units of the chain's native coin nativeTokenId.

This is an estimate only. Nothing is reserved and the price is not held: send the fee you showed as maxFee on the withdrawal if you need the charge to stay within it.

externalId really is an idempotency key here¶

This is the one write in the API where a repeated externalId is safe rather than an error. Send the same one twice with the same parameters — a retry after a socket timeout, a duplicated job — and the second call returns the existing withdrawal instead of raising a second one. It is scoped to your merchant.

externalId is optional, but leave it out only if you never retry. Without it every call is a new withdrawal: two identical requests are two payouts, and a retry after a timeout whose answer you never saw pays out twice.

The same externalId with any parameter changed — chainId, tokenId, to, toTag, amount, subtractFeeFromAmount or maxFee — is refused with 409 WITHDRAWAL_EXTERNAL_ID_CONFLICT, and nothing is paid out. It means your system reused one reference for two different payouts; fix the reference rather than retrying.

Contrast invoices, where a duplicate externalId is a 409. The asymmetry is deliberate: a duplicate invoice is recoverable, a duplicate withdrawal pays out twice.

A repeat returns the existing withdrawal whatever became of it, including a FAILED one. To try a failed withdrawal again, send a new externalId. A withdrawal refused with a 422 was never recorded, so the same externalId can be used again once the cause is fixed. After a 5xx the externalId stays taken: a retry with it returns whatever became of the first attempt.

Errors¶

Watching a withdrawal¶

curl "https://api.pay.nullswap.com/api/v1/merchant/withdrawals?limit=50" \
  -H "x-api-key: sk_live_..."

Only offset, limit and order — no filtering by status, token or externalId. Ordered by createdAt DESC by default.

{
  "id": "9c0d1e2f-3a4b-45c6-8d78-9e0f1a2b3c4d",
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "toAddress": "0xfedcba0987654321fedcba0987654321fedcba09",
  "toTag": null,
  "amount": "50000000",
  "fee": "1350000",
  "decimals": 6,
  "status": "CONFIRMED",
  "hash": "0x9a8b7c6d5e4f30211a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70819",
  "error": null,
  "createdAt": "2026-01-14T09:00:00.000Z",
  "updatedAt": "2026-01-14T09:04:00.000Z"
}

id is the transferRequestId you were handed at creation — the same value, renamed. amount is what the recipient is sent — already net of the fee if you set subtractFeeFromAmount — and fee what you were charged on top of it. toTag is the destination tag the payout was sent with on RIPPLE, null when it had none and on every other chain; toAddress is always the classic address, also when you sent an X-address. fee is null on a payout made before withdrawal fees were charged in the withdrawn token.

stateDiagram-v2
    [*] --> PENDING: POST accepted
    PENDING --> BROADCASTING: being sent
    BROADCASTING --> BROADCAST: published
    BROADCASTING --> FAILED: could not be sent
    PENDING --> FAILED: could not be sent
    BROADCAST --> CONFIRMED: confirmed on chain
    BROADCAST --> FAILED: reverted
    CONFIRMED --> [*]
    FAILED --> [*]

Two details to handle in that poller:

• hash can be null on a FAILED record, permanently. A withdrawal that failed before broadcast never had a hash. Check the field before rendering an explorer link.
• decimals is nullable. It is null if the token has since been delisted. Fall back to a cached value from /api/v1/tokens rather than defaulting to 18.

A withdrawal that fails before it reaches the chain gives back both the amount and the fee to your balance. One that was sent and then reverted gives back the amount only: the network fee was spent.

Two cases are not settled automatically, and neither looks different from the outside:

• A FAILED withdrawal that may have reached the chain. When a send times out in a way that leaves it unknown whether the transaction went out, the record is FAILED but nothing is given back, because the payout may still land. The record does not say which kind of FAILED it is: compare your balance, and contact support with the withdrawal id if the money did not return.
• A BROADCAST withdrawal the chain dropped. It stays BROADCAST, with nothing given back. If one stays BROADCAST well past the chain's confirmation time, contact support with its id and hash.

error is set only on FAILED, as a code: WITHDRAWAL_REVERTED — the transaction reached the chain and was reverted, the amount is back on your balance and the network fee is spent; WITHDRAWAL_FAILED — anything else, nothing was sent. Treat an unknown code as WITHDRAWAL_FAILED; more may be added.