Skip to navigation

Withdrawals & approvals

Send funds out, via API or the dashboard.

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:

curl -X POST https://api.cheddar.biz/v1/withdraw \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"mintId": 1,
"customerId": "your-customer-id",
"amount": "1.00",
"toAddress": "0x…",
"useDecimal": true,
"idempotencyKey": "your-withdrawal-ref-123"
}'
  • amount is in base units unless useDecimal: true, which interprets it as a whole-token decimal.
  • Set requireApproval: true to 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 withdrawalId is a UUID string. Store it as a string; it is the id on every withdrawal webhook.
  • A withdrawal blocked by risk screening returns 451, still with a withdrawalId.
  • A withdrawal that needs approval fires a CUSTOMER_WITHDRAW_AWAITING_APPROVAL webhook.
  • On chains with confirmation tracking you get CUSTOMER_WITHDRAW_PROCESSING when the withdrawal is first in a block (informational) and CUSTOMER_WITHDRAW once it is confirmed; elsewhere CUSTOMER_WITHDRAW fires on broadcast. A withdrawal that drops out of the chain fires CUSTOMER_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:

You sendResult
A new keyWithdrawal created.
The same key and the same request200 with the original withdrawalId and its current status. Nothing new is created.
The same key with a different request409.

“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 as idempotencyKey, so you can match it to your own record. The field is null if you sent no key.
  • Lookup: GET /withdrawals?idempotencyKey=your-withdrawal-ref-123.
  • Rejected or failed: a replay still returns the original withdrawal, and its status shows 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.

curl "https://api.cheddar.biz/v1/withdrawals/8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f" \
-H "x-api-key: YOUR_API_KEY"
curl "https://api.cheddar.biz/v1/withdrawals?withdrawalId=8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f" \
-H "x-api-key: YOUR_API_KEY"
{
"items": [
{
"id": "8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f",
"customerId": "your-customer-id",
"status": "CONFIRMED",
"awaitingApprovalReason": null,
"failureReason": null,
"mint": { "id": 1, "symbol": "USDC", "chain": "SOLANA" },
"amount": "1000000",
"uiAmount": "1",
"txHash": "5x…",
"toAddress": "…",
"scannerUrl": "https://solscan.io/tx/5x…",
"createdAt": "2026-11-01T10:00:00.000Z",
"confirmedAt": "2026-11-01T10:00:30.000Z",
"approvedAt": null,
"rejectedAt": null
}
],
"hasMore": false,
"nextCursor": null
}

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.

statusMeaning
PENDINGCreated, not yet broadcast or confirmed.
AWAITING_CONFIRMATIONHeld for approval — see awaitingApprovalReason.
CONFIRMEDSent on-chain.
FAILEDFailed — see failureReason.
REJECTEDRejected by your team (rejectedAt set).

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:

Wallet balance card with the Withdraw action
The wallet balance card in the left navigation, with the balance breakdown expanded and the actions menu open.
  1. Select Token and confirm the Network.
  2. Choose a Withdraw Address — only addresses on your organization’s whitelist are selectable. An empty whitelist blocks the action.
  3. Enter an Amount (or Max, which subtracts the network fee).
Withdraw Funds dialog with token, address, and amount fields
The Withdraw Funds dialog — token, whitelisted address, and amount.

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).

Transactions to Approve list
Transactions to Approve — pending withdrawals awaiting 2FA approval.

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).

  1. A held withdrawal fires CUSTOMER_WITHDRAW_AWAITING_APPROVAL (status AWAITING_CONFIRMATION).
  2. Send your decision:
curl -X POST "https://api.cheddar.biz/v1/withdrawals/8a1d4f6e-2b3c-4d5e-8f90-1a2b3c4d5e6f/review" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "decision": "APPROVE" }'

The response is the withdrawal, in the same shape as GET /withdrawals/{id}.

decisionResult
APPROVEStatus PENDING; Cheddar broadcasts it and sends CUSTOMER_WITHDRAW when it lands. If the main wallet is short and a treasury conversion starts, the status is PREFUNDING (with approvedAt set) until the conversion settles, then it is sent.
REJECTStatus REJECTED, failureReason: ADMIN_REJECT, and a CUSTOMER_FAILED_TO_WITHDRAW webhook. The REJECTED response is final, so you can refund the customer from it without waiting for the webhook.

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.