> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

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

## 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](/companies/api/reference/wallet-withdrawal-recipients-list); if the user has none yet, [save one](/companies/api/reference/wallet-withdrawal-recipient-create) 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](/companies/api/reference/wallet-withdrawals-list).


## OpenAPI

````yaml openapi.json POST /api/v2/wallet/withdrawals
openapi: 3.1.0
info:
  title: Agentcard API
  version: 2.0.0
  description: >-
    The Agentcard v2 API — connect your users and verify their identity from
    your own backend. Every call is authenticated with a platform access token
    minted from your `client_id` + `client_secret`.
servers:
  - url: https://api.agentcard.sh
    description: >-
      There is one base URL. Sandbox vs production is decided by the client
      credential you use, never by the host.
security:
  - platformToken: []
tags:
  - name: Authentication
    description: >-
      Exchange your client credentials for a platform access token, and
      introspect what a token acts as.
  - name: Connect
    description: >-
      Connect a user to your platform: send a one-time code, verify it, record
      consent, and keep the connection alive.
  - name: Identity verification
    description: >-
      Verify a connected user's identity: upload their ID, submit any extra
      fields we ask for, then show a short face scan.
  - name: Wallet funding
    description: >-
      Fund a connected user's wallet from your own UI — request a payment link,
      relay the phone verification code, and poll until the funds land.
  - name: Withdrawals
    description: >-
      Move money out of a connected user's wallet — to a saved bank account or a
      crypto address on Base. Transfers are processed manually by the Agentcard
      team, usually within 1-3 business days.
paths:
  /api/v2/wallet/withdrawals:
    post:
      tags:
        - Withdrawals
      summary: Request a withdrawal
      description: >-
        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.
      operationId: walletWithdraw
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - amount_cents
              properties:
                user_id:
                  type: string
                  description: The connected user's id.
                amount_cents:
                  type: integer
                  description: Amount in USD cents, 200 to 1000000.
                rail:
                  type: string
                  enum:
                    - bank
                    - address
                  default: bank
                recipient_id:
                  type: string
                  description: 'Bank rail: the saved destination to pay (`wrec_...`).'
                destination_address:
                  type: string
                  description: >-
                    Address rail: a 0x-prefixed address on Base to receive USDC.
                    Agentcard-managed addresses are rejected.
            example:
              user_id: usr_123
              amount_cents: 2500
              rail: bank
              recipient_id: wrec_9f2c1a
      responses:
        '200':
          description: The withdrawal, in `requested`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
              example:
                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'
        '400':
          description: Malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `withdrawals_disabled` — your organization has switched user
            withdrawals off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`connection_not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            `insufficient_funds` (details carry `available_cents` and
            `requested_cents`), `amount_out_of_range`, `recipient_not_found`,
            `invalid_destination`, or `internal_destination`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Withdrawal:
      type: object
      description: >-
        A withdrawal request. Both rails are processed manually: the status
        walks `requested` → `processing` → `completed` (or `rejected`), and the
        user is emailed at each step.
      properties:
        object:
          type: string
          enum:
            - withdrawal
        id:
          type: string
          description: Withdrawal id (`wd_...`).
        user_id:
          type: string
        status:
          type: string
          enum:
            - requested
            - processing
            - completed
            - rejected
        rail:
          type: string
          enum:
            - bank
            - address
          description: >-
            `bank` pays a saved recipient by wire; `address` sends USDC on Base
            to the supplied address.
        amount_cents:
          type: integer
        destination_address:
          type: string
          nullable: true
          description: 'Set on the `address` rail: the Base address receiving USDC.'
        failure_code:
          type: string
          nullable: true
          description: Set when rejected, e.g. `rejected_by_ops`.
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        recipient:
          $ref: '#/components/schemas/WithdrawalRecipient'
          nullable: true
          description: The saved bank destination, when the rail is `bank`.
    Error:
      type: object
      description: Every v2 error uses the same envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable string (snake_case). Branch on this.
            message:
              type: string
              description: A human-readable explanation, safe to log.
            docs:
              type: string
              description: A link back to the reference.
            field_errors:
              type: object
              additionalProperties:
                type: string
              description: Only on `invalid_fields` — names each field to fix.
            warnings:
              type: array
              items:
                type: string
              description: >-
                Only on document upload errors — actionable feedback safe to
                show the user.
    WithdrawalRecipient:
      type: object
      description: >-
        A saved bank destination. Account and IBAN numbers are always masked to
        their last four digits in responses.
      properties:
        object:
          type: string
          enum:
            - withdrawal_recipient
        user_id:
          type: string
          description: The connected user this destination belongs to.
        id:
          type: string
          description: >-
            Recipient id (`wrec_...`). Pass it as `recipient_id` when creating a
            withdrawal.
        type:
          type: string
          enum:
            - ach
            - international_wire
        nickname:
          type: string
          nullable: true
        beneficiary_name:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country of the bank account.
        currency:
          type: string
          nullable: true
        bank_name:
          type: string
          nullable: true
        account_number_last4:
          type: string
          nullable: true
          description: 'Masked, ACH only. Example: `••••6789`.'
        routing_number:
          type: string
          nullable: true
          description: ACH only.
        account_type:
          type: string
          enum:
            - checking
            - savings
          nullable: true
        iban_last4:
          type: string
          nullable: true
          description: Masked, international wire only.
        swift_code:
          type: string
          nullable: true
          description: International wire only.
        created_at:
          type: string
          format: date-time
  securitySchemes:
    platformToken:
      type: http
      scheme: bearer
      description: >-
        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.

````