Payouts API

A payout sends a token amount from the project’s hot wallet to an address you name: a refund, an affiliate payment, a customer withdrawal. It is signed on your server with the hot wallet key that only your server holds, and broadcast by the payout worker. See Payouts for the dashboard side and Hot wallet for setup.

Three endpoints take the API-Key header:

Not available through the API in this release: the address book (saved recipients), approving or rejecting a held payout, cancelling a payout, and editing limits. These are dashboard operations. Amounts are in token units; convert from USD with GET /api/v1/ticker.

Lifecycle

Normal path: pending-approval → pending → initiated → sent → processed. Treat payout.sent as the success event; payout.processed follows shortly after.

Automatic approval: when the project has automatic approval enabled and the payout’s USD value is at or below the project’s automatic approval maximum, an API request is created as pending with an approval time and no approver, and goes straight to the worker. Otherwise it is pending-approval with approvalReason above_auto_approve or auto_approve_disabled. Automatic approval never overrides the minimum, the recipient limits or the balance check.

POST /api/v1/withdrawal/merchant

Headers: API-Key, Content-Type: application/json, optional Idempotency-Key.

curl -X POST https://<your-site>/api/v1/withdrawal/merchant \
  -H "API-Key: 811b12035f0dfa8ffd62296df3c98b27" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-8812" \
  -d '{
    "email": "[email protected]",
    "blockchainCode": "SOLANA",
    "currencyCode": "USDC",
    "amount": "100",
    "toAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
    "customerID": "1234"
  }'

Idempotency-Key: 1 to 128 printable non-space ASCII characters, scoped to the project. A replay with the same key and the same email, address, chain, currency, amount and customer returns 201 with the payout’s current record, even if the currency has since been disabled. The same key with different terms is 409 PAYOUT_DUPLICATE_REQUEST. Without a key, a request whose project, address, amount, currency and chain match a payout created within payout.duplicateWindowSeconds (default 300; 1 to 86400) by the API or the dashboard is 409 PAYOUT_DUPLICATE_REQUEST.

Checks, in USD at a fresh price, per recipient email per project: the minimum (payout.minimumUsd, default 1, or the project’s own minimum), the hourly and daily limits, and the automatic approval maximum. The token amount plus every non-terminal payout from the same hot wallet must fit the wallet’s current balance.

201 Created

{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "updatedAt": "2026-06-19T13:14:41.806Z",
  "blockchainCode": "SOLANA",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "toAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "recipientEmail": "[email protected]",
  "txHash": null,
  "status": "pending-approval",
  "type": "payout_merchant",
  "attributes": "{\"approvalReason\":\"above_auto_approve\"}",
  "createdBy": "api",
  "fromAddress": null,
  "failureReason": null,
  "webhookStatus": "pending",
  "fee": null
}

Errors

Creation, customer upsert, balance reservation and the webhook row are one transaction; on any failure nothing is stored.

GET /api/v1/withdrawal/{id}/merchant

curl https://<your-site>/api/v1/withdrawal/120/merchant \
  -H "API-Key: 811b12035f0dfa8ffd62296df3c98b27"

200 OK with the same object as the create response, at its current state:

{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "updatedAt": "2026-06-19T13:18:02.114Z",
  "blockchainCode": "SOLANA",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "toAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "recipientEmail": "[email protected]",
  "txHash": "5KjP2n8vQ4wR7tY1uI3oA6sD9fG2hJ4kL7zX0cV5bN8mQ1wE3rT6yU9iO2pA5sD8f",
  "status": "sent",
  "type": "payout_merchant",
  "attributes": "{}",
  "createdBy": "api",
  "fromAddress": "HotWa11etAddre55xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "failureReason": null,
  "webhookStatus": "received",
  "fee": "0.000005"
}

Errors: 400 BAD_REQUEST when id is not an integer in range, 401 UNAUTHORIZED, 404 NOT_FOUND (Payout not found) when the id is unknown or belongs to another project, 429 RATE_LIMITED.

GET /api/v1/withdrawal/merchant

curl "https://<your-site>/api/v1/withdrawal/merchant?status[]=sent&status[]=processed&createdAfter=2026-09-01T00:00:00Z&limit=50&sortBy=id&order=ASC" \
  -H "API-Key: 811b12035f0dfa8ffd62296df3c98b27"

Repeat array parameters with the bracket name: status[]=pending&status[]=sent. A single value without repetition also works.

200 OK, a bare JSON array of payout objects in the shape of the single read. Paginate with offset, or with greaterThanID and sortBy=id&order=ASC for a stable cursor, until a page returns fewer rows than the effective page size. Because a requested limit above the cap is silently clamped, compare against the number of rows you receive, not against the limit you sent.

Errors: 400 BAD_REQUEST for any parameter outside its constraints or an inverted range, 401 UNAUTHORIZED, 429 RATE_LIMITED, 503 UNAVAILABLE when payout.listPageCap is invalid.

Payout webhooks

Every persisted status transition posts one event to every active endpoint of the project, with the same headers, signature, retry schedule and delivery guarantees as the payment webhook. Idempotency on the sending side is per payout and status, so one status produces one delivery per endpoint. Resending an approval code or adding a note produces no event.

The payload status is the database status in upper case with underscores, so it does not always match the event name (payout.approved carries PENDING).

{
  "event_type": "payout.sent",
  "payout_id": 120,
  "network": "SOLANA",
  "token": "USDC",
  "amount": "100",
  "amount_usd": "100.000000",
  "email": "[email protected]",
  "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "from_address": "HotWa11etAddre55xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "tx_hash": "5KjP2n8vQ4wR7tY1uI3oA6sD9fG2hJ4kL7zX0cV5bN8mQ1wE3rT6yU9iO2pA5sD8f",
  "status": "SENT",
  "withdrawal_type": "payout_merchant",
  "currency_type": "token",
  "created_at": 1750340081,
  "updated_at": 1750340282,
  "timestamp": 1750340282,
  "failure_reason": "",
  "network_fee_raw": "5000"
}

Handle payout events like payment events: verify the signature, deduplicate on X-Recv-Delivery, and expect duplicates and out-of-order arrivals. The initiated event is committed before the broadcast is attempted, so an initiated followed by nothing for a while means the worker is waiting for confirmations or for the next attempt, not that the payout was lost; read the payout to see its current status.