Skip to main content
POST
/
v1
/
payout
/
accounts
/
setup
/
liquidation-address
Set up a payout account — Step 1
curl --request POST \
  --url https://api.example.com/v1/payout/accounts/setup/liquidation-address \
  --header 'Content-Type: application/json' \
  --data '
{
  "beneficiaryId": "<string>",
  "beneficiaryAccountId": "<string>",
  "chain": "<string>",
  "currency": "<string>"
}
'
{
  "id": "<string>",
  "address": "<string>",
  "chain": "<string>",
  "currency": "<string>"
}
This endpoint is step 1 of the 2-step payout account setup for off-ramp settlement. It links a recipient’s bank account to a crypto withdrawal address. When stablecoins land at this address, the off-ramp transfer to the recipient’s bank is triggered automatically.
1

Step 1 — POST /v1/payout/accounts/setup/liquidation-address (this endpoint)

Creates or returns the withdrawal address for (beneficiaryId, beneficiaryAccountId, chain, currency). Idempotent — calling twice returns the same address.
2

Step 2 — POST /v1/payout/accounts/setup/virtual-account

Creates a fiat virtual account (e.g. a SPEI CLABE in Mexico) tied to the withdrawal address. Returns the account number your client deposits fiat into. Also idempotent.
3

Operate — quote and execute

Use POST /v1/payout/accounts/quote and POST /v1/payout/accounts/execute to move money. Track via GET /v1/orders/{orderId}.
Both setup endpoints are idempotent. You can call them on every order without worrying about duplicates. This is the recommended pattern: don’t cache setup IDs in your backend, just call setup before each payment.

​
Prerequisites

  • Workspace KYB completed (one-time, via dashboard)
  • Recipient created (POST /v1/payout/recipients)
  • Recipient’s bank account added (POST /v1/payout/recipients/{id}/accounts or via invite link)

​
Request body

​
beneficiaryId
string
required
Recipient ID (from POST /v1/payout/recipients).
​
beneficiaryAccountId
string
required
The recipient’s bank account ID (from POST /v1/payout/recipients/{id}/accounts).
​
chain
string
required
Stablecoin chain. Supported: base, polygon, arbitrum, solana. More on request.
​
currency
string
required
Stablecoin symbol on the chosen chain. Supported: usdc, usdt.

​
Response

​
id
string
Internal withdrawal address ID. You generally don’t need to store this — call setup again to retrieve.
​
address
string
The crypto address. Send stablecoins here to trigger an off-ramp settlement to the recipient’s bank.
​
chain
string
Echo of the chain you requested.
​
currency
string
Echo of the stablecoin you requested.
Each (beneficiaryAccountId, chain, currency) triple maps to one withdrawal address forever. Different recipients get different addresses. Don’t reuse addresses across recipients.

​
What happens after a deposit?

When stablecoins arrive at the returned address, the off-ramp partner detects the deposit, settles the on-chain leg, and initiates the fiat transfer to the recipient’s bank. Track the full lifecycle as an order: 
GET /v1/orders                  — list all orders
GET /v1/orders/{orderId}        — get a single order with timeline
GET /v1/payout/recipients/{id}/orders  — orders for this recipient
Typical timeline: stablecoin deposit detected → confirmed on-chain → fiat transfer submitted → fiat received at recipient bank. End-to-end takes 1–2 business days via SPEI.

​
Authentication

Authorization: ApiKey rk_client_key_v1_... — workspace key with payout module enabled and payout:write scope.

​
Common errors

StatusCauseFix
400Unsupported chain + currency combinationSee /v1/action/tokens/{chain}/usdc for supported pairs
403payout module not active for workspaceActivate Payout Kit in the dashboard
404beneficiaryId or beneficiaryAccountId not found, or belongs to another workspaceCross-tenant lookups always return 404 (no existence leak)
422Recipient’s bank account is not yet usable (pending registration)Wait for the rails partner to confirm the bank account, then retry

​
Next steps

  • POST /v1/payout/accounts/setup/virtual-account — Step 2: create the fiat virtual account
  • Payout Kit Flow Guide — full end-to-end narrative with code samples
  • POST /v1/payout/accounts/quote then POST /v1/payout/accounts/execute — operate once setup is complete