Request a withdrawal

curl --request POST \
  --url https://api.agentcard.sh/api/v2/wallet/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123",
  "amount_cents": 2500,
  "rail": "bank",
  "recipient_id": "wrec_9f2c1a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: 'usr_123',
    amount_cents: 2500,
    rail: 'bank',
    recipient_id: 'wrec_9f2c1a'
  })
};

fetch('https://api.agentcard.sh/api/v2/wallet/withdrawals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/wallet/withdrawals"

payload = {
    "user_id": "usr_123",
    "amount_cents": 2500,
    "rail": "bank",
    "recipient_id": "wrec_9f2c1a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "withdrawal",
  "id": "wd_4b1d22",
  "user_id": "usr_123",
  "status": "requested",
  "rail": "bank",
  "amount_cents": 2500,
  "destination_address": null,
  "created_at": "2026-07-16T00:00:00.000Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

Withdrawals

Request a withdrawal

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.

POST

api

wallet

withdrawals

Request a withdrawal

curl --request POST \
  --url https://api.agentcard.sh/api/v2/wallet/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123",
  "amount_cents": 2500,
  "rail": "bank",
  "recipient_id": "wrec_9f2c1a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: 'usr_123',
    amount_cents: 2500,
    rail: 'bank',
    recipient_id: 'wrec_9f2c1a'
  })
};

fetch('https://api.agentcard.sh/api/v2/wallet/withdrawals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/wallet/withdrawals"

payload = {
    "user_id": "usr_123",
    "amount_cents": 2500,
    "rail": "bank",
    "recipient_id": "wrec_9f2c1a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "withdrawal",
  "id": "wd_4b1d22",
  "user_id": "usr_123",
  "status": "requested",
  "rail": "bank",
  "amount_cents": 2500,
  "destination_address": null,
  "created_at": "2026-07-16T00:00:00.000Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

How it works

Requests a withdrawal from the user’s spendable balance. Two rails:

bank (default) — pays a saved destination by ACH or international wire. Pass the recipient_id from saved destinations; if the user has none yet, save one first.
address — sends USDC on Base to destination_address (a 0x address the user provides). Agentcard-managed addresses are rejected (internal_destination).

Both rails are processed manually by the Agentcard team, usually within 1-3 business days — set that expectation in your UI. The response comes back in requested; the status then walks requested → processing → completed (or rejected), and the user is emailed when the request is received and again when it is sent.

Amounts range from $2.00 to$ 10,000.00 per request.
Open requests hold the balance: they count against the user’s spendable balance until they complete or are rejected, so a user can never over-request. insufficient_funds returns available_cents — the balance net of holds — for a helpful retry message.
Only what the user can actually spend is withdrawable. Money your company allocated to a user under the company-funded flow is not.
You can switch user withdrawals off for your whole organization from the dashboard (Settings → General → User withdrawals); while off, these endpoints return withdrawals_disabled.

Track progress with list withdrawals.

Authorizations

Authorization

string

header

required

A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.

Body

application/json

user_id

string

required

The connected user's id.

amount_cents

integer

required

Amount in USD cents, 200 to 1000000.

rail

enum<string>

default:bank

Available options:

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

The withdrawal, in requested.

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

enum<string>

Available options:

withdrawal

string

Withdrawal id (wd_...).

user_id

string

status

enum<string>

Available options:

requested,

processing,

completed,

rejected

rail

enum<string>

bank pays a saved recipient by wire; address sends USDC on Base to the supplied address.

Available options:

bank,

address

amount_cents

integer

destination_address

string | null

Set on the address rail: the Base address receiving USDC.

failure_code

string | null

Set when rejected, e.g. rejected_by_ops.

completed_at

string<date-time> | null

created_at

string<date-time>

recipient

object | null

The saved bank destination, when the rail is bank.

Show child attributes

Remove a bank destination List withdrawals

⌘I

Authentication

Connect

Card attachment

Identity verification

Balance funding

Withdrawals

Platform connect

Request a withdrawal

How it works

Authorizations

Body

Response

​How it works

Authorizations

Body

Response

How it works