Payouts

Pay your collected net balance to your whitelisted address. Payouts are asynchronous: Hbridge sweeps funds into your treasury, then sends the net to your payout address.

Set payout address#

Do this once per chain before your first payout. The address must be whitelisted in the custody layer, otherwise payouts will stay pending and eventually fail.

PUT/v1/payout-address

Register (or update) your payout destination for a chain. The address must be whitelisted in the custody layer before payouts can complete.

Body
FieldTypeRequiredDescription
chainstringyesChain code, e.g. ETH.
addressstringyesYour receiving address on that chain.
Request
PUT /v1/payout-address
{
  "chain": "ETH",
  "address": "0xfCd9C810F83f7E3255Eb4F41ff9A6310146117B6"
}
200 Response
{ "chain": "ETH", "address": "0xfCd9...17B6" }

Request payout#

Kick off a payout of a (chain, token) balance. It returns immediately with a pending settlement; the funds settle on-chain asynchronously. Always send an Idempotency-Keyso a retry can't pay out twice.

POST/v1/payouts

Request a payout of the net balance for a (chain, token). Returns 202 with a pending settlement; track it via the sections below or the payout.completed / payout.failed webhooks. An unsupported pair returns 422 unsupported_token; a business/custody failure returns 422 payout_failed.

Headers
FieldTypeRequiredDescription
Idempotency-KeystringnoSafely retry a payout request: a repeat with the same key returns the original settlement instead of creating a second one.
Body
FieldTypeRequiredDescription
chainstringyesChain code, e.g. ETH.
tokenstringyesToken symbol, e.g. USDC.
sweep_firstbooleannoForce an on-demand sweep before sending (usually implicit).
Request
POST /v1/payouts
Idempotency-Key: 3f8c1e5a-...

{
  "chain": "ETH",
  "token": "USDC"
}
202 Response
{
  "id": "6c98...",
  "status": "pending",
  "gross": "2",
  "fee": "0.01",
  "net": "1.99",
  "txid": null
}

List payouts#

GET/v1/payouts

List your payouts (settlements), newest first. Paginated.

Query
FieldTypeRequiredDescription
limitnumbernoPage size, 1–200, default 50.
cursorstringnoPrevious response's next_cursor for the next page.
200 Response
{
  "payouts": [
    {
      "id": "6c98...",
      "status": "completed",
      "chain": "ETH",
      "token": "USDC",
      "gross": "2",
      "fee": "0.01",
      "net": "1.99",
      "txid": "0x98acc127...",
      "error": null,
      "created_at": "2026-07-02T10:10:00.000Z"
    }
  ],
  "next_cursor": "6c98...",
  "has_more": true
}

Get payout#

GET/v1/payouts/:id

Fetch a single payout's status. Statuses progress pending → sweeping → swept → paying → completed (or failed).

Path
FieldTypeRequiredDescription
idstringyesThe payout (settlement) id.
200 Response
{
  "id": "6c98...",
  "status": "completed",
  "chain": "ETH",
  "token": "USDC",
  "gross": "2",
  "fee": "0.01",
  "net": "1.99",
  "txid": "0x98acc127...",
  "error": null
}
PreviousDeposits & balancesNextWebhooks & events