Withdrawals & approvals
Every withdrawal status (PENDING, AWAITING_CONFIRMATION, PROCESSING,
CONFIRMED, FAILED, …) is explained in Transaction
statuses.
Customer withdrawals (API)
POST /withdraw sends funds from a customer’s balance to an address:
amountis in base units unlessuseDecimal: true, which interprets it as a whole-token decimal.- Set
requireApproval: trueto force manual approval. If the customer’s email is on your active withdrawal approval email allowlist, that override skips this flag and the customer USD withdraw-threshold hold (destination-address, low-liquidity, and risk gates still apply). - The response’s
withdrawalIdis a UUID string. Store it as a string; it is theidon every withdrawal webhook. - A withdrawal blocked by risk screening returns
451, still with awithdrawalId. - A withdrawal that needs approval fires a
CUSTOMER_WITHDRAW_AWAITING_APPROVALwebhook. - On chains with confirmation tracking you get
CUSTOMER_WITHDRAW_PROCESSINGwhen the withdrawal is first in a block (informational) andCUSTOMER_WITHDRAWonce it is confirmed; elsewhereCUSTOMER_WITHDRAWfires on broadcast. A withdrawal that drops out of the chain firesCUSTOMER_FAILED_TO_WITHDRAW. See Transaction statuses.
Idempotency key (your reference)
idempotencyKey is optional (1–255 characters). Use your own reference for the
withdrawal, such as your payout ID, so retries are safe:
“The same request” means the same customerId, mintId, amount (compared in base
units) and toAddress.
- Webhooks: every withdrawal event (
CUSTOMER_WITHDRAW,CUSTOMER_WITHDRAW_AWAITING_APPROVAL,CUSTOMER_FAILED_TO_WITHDRAW) includes your key asidempotencyKey, so you can match it to your own record. The field isnullif you sent no key. - Lookup:
GET /withdrawals?idempotencyKey=your-withdrawal-ref-123. - Rejected or failed: a replay still returns the original withdrawal, and its
statusshows nothing will be sent. To try again, use a new key. - Risk-blocked (
451): the key is not used up, so you can send it again.
Check withdrawal status
If a webhook did not reach you, GET /withdrawals returns each withdrawal’s
current state. Look one up by the withdrawalId that POST /withdraw
returned (the same id as on the withdrawal webhooks), or list by customer and
time window. GET /withdrawals/{id} returns that one withdrawal as an object
(404 if unknown); the list endpoint wraps results in items.
Filters: withdrawalId, customerId, txHash, status, from / to
(ISO-8601 on createdAt), limit (1–100, default 20) and cursor (the
previous page’s nextCursor, a UUID). amount is always positive, in base units.
Organization withdrawals (dashboard)
The wallet balance card at the bottom of the left navigation is the entry point on every dashboard page. Expand it to see the balance per product (Custodial, Checkout, Batch Payout), then open its actions menu → Withdraw:

- Select Token and confirm the Network.
- Choose a Withdraw Address — only addresses on your organization’s whitelist are selectable. An empty whitelist blocks the action.
- Enter an Amount (or Max, which subtracts the network fee).

Whitelisted destination addresses are managed by the Cheddar team — see Organization security. To skip manual approval holds for trusted customer emails, use the separate Withdrawal approval email allowlist.
Approving withdrawals
Withdrawals above your 2FA threshold land in Dashboard → Custodial →
Transactions to Approve (/dashboard/transactions-to-approve). Each row can be
Approved (broadcasts it) or Removed (rejects it).

Approving held customer withdrawals via API
If you review held customer withdrawals in your own system, approve or reject them
with your API key instead of the dashboard. This is off by default; ask Cheddar to
enable it for your organization (otherwise 403 FORBIDDEN).
- A held withdrawal fires
CUSTOMER_WITHDRAW_AWAITING_APPROVAL(statusAWAITING_CONFIRMATION). - Send your decision:
The response is the withdrawal, in the same shape as GET /withdrawals/{id}.
Errors: 409 NOT_AWAITING_APPROVAL when the withdrawal was already decided (by
you, a retry, or the dashboard), including when two decisions race; only the first
takes effect. Call GET /withdrawals/{id} to see its state. A 500 on APPROVE
leaves the withdrawal on hold (AWAITING_CONFIRMATION), so it is safe to retry.
422 INSUFFICIENT_LIQUIDITY or PREFUND_FAILED apply to APPROVE only; top up
the main wallet and retry, or reject.