---
title: "Request a withdrawal"
method: POST
path: "/api/v2/wallet/withdrawals"
tags: ["Withdrawals"]
---

# Request a withdrawal

`POST /api/v2/wallet/withdrawals`

Requests a withdrawal from the user's spendable balance. Two rails: `bank` (default) pays a saved destination by wire; `address` sends USDC on Base to `destination_address`. Both are processed manually by the Agentcard team, usually within 1-3 business days; the user is emailed when the request is received and again when it is sent. Open (not yet completed or rejected) requests count against the balance, so a user cannot over-request. Amounts range from $2.00 to $10,000.00.

## Request body

- object
  - `user_id` string, required — The connected user's id.
  - `amount_cents` integer, required — Amount in USD cents, 200 to 1000000.
  - `rail` 'bank' | 'address'
  - `recipient_id` string — Bank rail: the saved destination to pay (`wrec_...`).
  - `destination_address` string — Address rail: a 0x-prefixed address on Base to receive USDC. Agentcard-managed addresses are rejected.

## Response `200`

The withdrawal, in `requested`.

- Withdrawal — A withdrawal request. Both rails are processed manually: the status walks `requested` → `processing` → `completed` (or `rejected`), and the user is emailed at each step.
  - `object` 'withdrawal'
  - `id` string — Withdrawal id (`wd_...`).
  - `user_id` string
  - `status` 'requested' | 'processing' | 'completed' | 'rejected'
  - `rail` 'bank' | 'address' — `bank` pays a saved recipient by wire; `address` sends USDC on Base to the supplied address.
  - `amount_cents` integer
  - `destination_address` string, nullable — Set on the `address` rail: the Base address receiving USDC.
  - `failure_code` string, nullable — Set when rejected, e.g. `rejected_by_ops`.
  - `completed_at` string, date-time, nullable
  - `created_at` string, date-time
  - `recipient` WithdrawalRecipient — A saved bank destination. Account and IBAN numbers are always masked to their last four digits in responses.
    - `object` 'withdrawal_recipient'
    - `user_id` string — The connected user this destination belongs to.
    - `id` string — Recipient id (`wrec_...`). Pass it as `recipient_id` when creating a withdrawal.
    - `type` 'ach' | 'international_wire'
    - `nickname` string, nullable
    - `beneficiary_name` string
    - `country_code` string — ISO 3166-1 alpha-2 country of the bank account.
    - `currency` string, nullable
    - `bank_name` string, nullable
    - `account_number_last4` string, nullable — Masked, ACH only. Example: `••••6789`.
    - `routing_number` string, nullable — ACH only.
    - `account_type` 'checking' | 'savings', nullable
    - `iban_last4` string, nullable — Masked, international wire only.
    - `swift_code` string, nullable — International wire only.
    - `created_at` string, date-time

## Other responses

- `400` — Malformed request body.
- `403` — `withdrawals_disabled` — your organization has switched user withdrawals off.
- `404` — `connection_not_found`.
- `422` — `insufficient_funds` (details carry `available_cents` and `requested_cents`), `amount_out_of_range`, `recipient_not_found`, `invalid_destination`, or `internal_destination`.

---

[API](https://skmtc.dev/agentcard/apis/agentcard-api.md) · [All operations](https://skmtc.dev/agentcard/apis/agentcard-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentcard/agentcard-api/revisions/638d12c8303f/schema)