> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://doc.cheddar.biz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://doc.cheddar.biz/_mcp/server.

# Withdrawals & approvals

Every withdrawal status (`PENDING`, `AWAITING_CONFIRMATION`, `PROCESSING`,
`CONFIRMED`, `FAILED`, …) is explained in [Transaction statuses](/guides/transaction-statuses).

## Customer withdrawals (API)

`POST /withdraw` sends funds from a customer's balance to an address:

```bash
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](/guides/withdrawal-approval-emails),
  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](/webhooks/events).
* 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](/guides/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 send                              | Result                                                                                       |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| A new key                             | Withdrawal created.                                                                          |
| The same key and the same request     | `200` with the **original** `withdrawalId` and its current `status`. Nothing new is created. |
| The same key with a different request | `409`.                                                                                       |

"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`.

```bash
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"
```

```json
{
  "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.

| `status`                | Meaning                                           |
| ----------------------- | ------------------------------------------------- |
| `PENDING`               | Created, not yet broadcast or confirmed.          |
| `AWAITING_CONFIRMATION` | Held for approval — see `awaitingApprovalReason`. |
| `CONFIRMED`             | Sent on-chain.                                    |
| `FAILED`                | Failed — see `failureReason`.                     |
| `REJECTED`              | Rejected 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](/_fern-files/_img/c3a5f7408b808a2c894e7e125543ffbe71ec29209909e4370b662b8f9e18a3ca.webp)

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](/_fern-files/_img/c92e8f192f711746823b7df1b27c9f519bbdd80b70142cc7d1a2a935f81f9f55.webp)

Whitelisted **destination addresses** are managed by the Cheddar team — see
[Organization security](/guides/organization). To skip manual approval holds for
trusted **customer emails**, use the separate
[Withdrawal approval email allowlist](/guides/withdrawal-approval-emails).

## 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](/_fern-files/_img/4f6a52e842dc7776251dc5d6dcd7a8492806d858e9b18654b4e7e61ffad866d5.webp)

### 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:

```bash
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}`.

| `decision` | Result                                                                                                                                                                                                                                               |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPROVE`  | Status `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. |
| `REJECT`   | Status `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.