> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}. > Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts. > Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md. > Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md. > Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers. > Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews. > Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming. > Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md. > Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors. > API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product. > Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes. > When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records. > Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md. # Create an account bank withdrawal > Create a bank withdrawal from an account. This converts a digital asset to fiat currency and sends it to the specified destination bank account. ## OpenAPI ````yaml openapi/accounts.yaml post /v1/accounts/withdrawals openapi: 3.1.0 info: version: 1.0.0 title: Accounts (Stablecoin) API description: > Circle's Accounts API provides endpoints for managing stablecoin accounts -- including transfers, withdrawals, deposits, wire and ACH bank accounts, and blockchain addresses. An **Account** is a general representation of a ledger or custody object that holds balances. It can be a business account, a stablecoin account ledger for an end user, an extra sub-ledger, or any future custody solution. license: name: Circle License url: https://circle.com/terms servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Accounts description: Manage accounts. - name: Account Groups description: Manage custody account groups and their memberships. - name: Limits description: View effective account limits and current usage. - name: Transfers description: > Move funds between accounts or out to a verified blockchain address, and track inbound and outbound onchain transfers. - name: Transactions description: | Get a unified, customer-friendly view of account transaction activity. - name: Wires description: Manage account bank accounts for wire transfers. - name: Deposits description: Get information on account bank deposits. - name: Withdrawals description: Manage account bank withdrawals (fiat offramp). - name: ACH description: Manage account bank accounts for ACH transfers. - name: Deposit Addresses description: Manage account deposit addresses. - name: Recipient Addresses description: Manage account recipient addresses used for transfers. - name: Passkeys description: > Manage WebAuthn passkeys and Strong Customer Authentication (SCA) challenges for end users. - name: Crypto Payments description: > Get crypto payments and crypto refunds received through payment intents. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payments. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Crypto Payment Intents description: > Create, expire, refund, and track payment intents for receiving crypto payments. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payments. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Crypto Payouts description: > Create and track crypto payouts to recipient addresses. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payouts. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Crypto Address Book description: > Manage address book recipients used as crypto payout destinations. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payouts. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: FX Trades description: | Quote and execute USDC <> EURC swaps for end users' accounts. - name: FX Settlements description: Get settlements of FX trades. - name: Webhook Subscriptions description: Manage subscriptions to Digital Asset Accounts webhook notifications. - name: Webhooks description: | Webhook event payloads Circle sends to a subscribed endpoint. paths: /v1/accounts/withdrawals: post: tags: - Withdrawals summary: Create an account bank withdrawal description: > Create a bank withdrawal from an account. This converts a digital asset to fiat currency and sends it to the specified destination bank account. operationId: createAccountWithdrawal parameters: - $ref: '#/components/parameters/ScaChallengeId' - $ref: '#/components/parameters/ScaAssertion' requestBody: content: application/json: schema: $ref: '#/components/schemas/AccountWithdrawalCreationRequest' responses: '201': description: Successfully created a withdrawal. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/CreateAccountWithdrawalResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' '403': $ref: '#/components/responses/ScaForbidden' '404': $ref: '#/components/responses/ScaChallengeNotFound' '410': $ref: '#/components/responses/ScaChallengeExpired' '413': $ref: '#/components/responses/RequestTooLarge' '428': $ref: '#/components/responses/ScaRequired' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ScaUnavailable' security: - bearerAuth: [] components: parameters: ScaChallengeId: name: X-Sca-Challenge-Id in: header required: false description: > The `challengeId` returned by `POST /v1/accounts/passkeys/challenges`. Required for end users under EEA/FR legal entities (PSD2 SCA). Omit for all other end users. schema: type: string format: uuid example: b2c3d4e5-f6a7-8901-bc23-def456789012 ScaAssertion: name: X-Sca-Assertion in: header required: false description: > The signed assertion string returned by the DAA web SDK's `sca.approve` method. Required for end users under EEA/FR legal entities (PSD2 SCA). Pass the value through unchanged — do not base64-encode or re-serialize it. schema: type: string schemas: AccountWithdrawalCreationRequest: type: object required: - idempotencyKey - destination - amount - riskSignals properties: idempotencyKey: $ref: '#/components/schemas/IdempotencyKey' source: description: | The source account for the withdrawal. The type must be `account`. type: object required: - id - type properties: id: description: > Identifier of the source account created via [POST /v1/accounts](#operation/createAccount). type: string example: '1000565227' type: type: string enum: - account destination: $ref: '#/components/schemas/BusinessDestinationRequest' amount: $ref: '#/components/schemas/FiatMoney' toAmount: $ref: '#/components/schemas/FiatPayoutToMoney' description: To be used when requesting currency exchange. burnAll: type: boolean default: false description: > If true, withdraw the full balance of all sub-accounts and the main wallet in a single operation. The source must be the main wallet. When set, `amount.amount` is ignored and `amount.currency` must be USD. riskSignals: $ref: '#/components/schemas/RiskSignals' CreateAccountWithdrawalResponse: title: CreateAccountWithdrawalResponse properties: data: $ref: '#/components/schemas/BusinessPayout' IdempotencyKey: type: string description: >- Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. format: uuid example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 BusinessDestinationRequest: type: object description: The destination bank account. required: - type - id properties: type: $ref: '#/components/schemas/BusinessAccountPayoutDestinationType' id: type: string description: > The ID of a bank account created via [POST /v1/banks/wires](#operation/createWireAccount). format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 FiatMoney: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: $ref: '#/components/schemas/FiatCurrency' FiatPayoutToMoney: type: object required: - currency properties: amount: description: Magnitude of the amount, in units of the currency, with a `.`. type: string example: '3.14' readOnly: true currency: $ref: '#/components/schemas/FiatCurrency' RiskSignals: type: object description: > Risk metadata for the end user initiating the request. All three fields must be present. `deviceId` must be the identifier returned by `checkDevice()` in the `@circle-fin/device-checks` SDK. Circle resolves it against the device check that produced it, so an identifier you generate yourself does not resolve. When it does not resolve, the request is accepted and then declined: the endpoint returns `201`, and the transaction later settles as `failed` with `errorCode` `transfer_denied`. See [Collect device risk signals](https://developers.circle.com/end-user-onboarding/howtos/collect-device-risk-signals). required: - ipAddress - sessionId - deviceId properties: ipAddress: type: string description: IP address of the end user initiating the request. example: 203.0.113.42 sessionId: type: string description: Identifier for the end user's session. example: 8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c deviceId: type: string description: > The identifier returned by `checkDevice()` in the `@circle-fin/device-checks` SDK. Store that value and send it here. Do not generate your own device identifier: Circle looks this value up against the completed device check, and an unrecognized value causes the transaction to be declined after the endpoint has already returned `201`. example: 2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f XRequestId: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde BusinessPayout: type: object properties: id: $ref: '#/components/schemas/Id' sourceAccountId: type: string description: Identifier of the source account. destination: $ref: '#/components/schemas/BankDestination' amount: $ref: '#/components/schemas/FiatMoney' toAmount: $ref: '#/components/schemas/FiatPayoutToMoney' fees: $ref: '#/components/schemas/FiatMoneyUsd' status: $ref: '#/components/schemas/PayoutStatus' trackingRef: type: - string - 'null' description: >- Payout tracking reference. This is only available once the payout has been successfully submitted to the bank. errorCode: $ref: '#/components/schemas/PayoutErrorCode' externalRef: $ref: '#/components/schemas/Id' riskEvaluation: $ref: '#/components/schemas/RiskEvaluation' adjustments: $ref: '#/components/schemas/FinalAdjustments' return: $ref: '#/components/schemas/UnwithdrawalObject' description: type: - string - 'null' description: > A free-form description echoed from the original create request. Omitted when unset. customerExternalRef: type: - string - 'null' description: > Customer-supplied external reference echoed back on the response and on payout webhooks. Useful for correlating payouts with external systems. Omitted when unset. burnAll: type: - boolean - 'null' description: > True when this withdrawal includes all sub-account and main wallet balances. Only present when `burnAll` was set on the create request. subAccountSweeps: type: - array - 'null' description: > Breakdown of the withdrawal amount per sub-account. Only present on burn-all withdrawals. items: $ref: '#/components/schemas/SubAccountSweep' createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' Error: type: object required: - code - message properties: code: type: integer description: > Circle internal status code from the platform `CoreStatusCode` enum (and its domain-specific extensions). **This is not the HTTP status code** — `-1` is the catch-all unknown error, `1`/`2` indicate API parameter problems, `3` is forbidden, `4` is unauthorized, and larger values identify domain-specific failures. Consumers should rely on the HTTP status line for transport-level error class and on this field for the specific Circle error case. example: 2 message: type: string description: >- Internal error message; suitable for logging but not for end-user display. example: API parameter invalid. externalMessage: type: string description: > End-user-displayable error message. Present when the server has generated a customer-facing variant for this error; omitted otherwise. example: The provided amount exceeds the maximum allowed. errors: type: array description: Additional request-field validation errors, when available. items: $ref: '#/components/schemas/ErrorDetail' BusinessAccountPayoutDestinationType: type: string description: The destination bank account type. example: wire enum: - wire - ach - fednow FiatCurrency: type: string description: Currency code. title: Currency enum: - USD - EUR example: USD Id: type: string description: Unique system-generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 BankDestination: type: object description: The destination bank account. required: - type - id properties: type: $ref: '#/components/schemas/BusinessAccountPayoutDestinationType' id: type: string description: > The ID of a bank account created via [POST /v1/banks/wires](#operation/createWireAccount). format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 name: type: string description: Bank name plus last four digits of the bank account number or IBAN. example: COMMERZBANK AG ****3000 FiatMoneyUsd: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: description: Currency code. type: string enum: - USD PayoutStatus: type: string description: >- Status of the payout. Status `pending` indicates that the payout is in process; `complete` indicates it finished successfully; `failed` indicates it failed. enum: - pending - complete - failed PayoutErrorCode: type: - string - 'null' description: >- Indicates the failure reason of a payout. Only present for payouts in a failed state. enum: - insufficient_funds - transaction_denied - transaction_failed - transaction_returned - bank_transaction_error - fiat_account_limit_exceeded - invalid_bank_account_number - invalid_ach_rtn - invalid_wire_rtn - vendor_inactive - payout_canceled - invalid_travel_rule_identity - intermediary_bank_required - sen_not_supported RiskEvaluation: type: - object - 'null' description: >- Results of risk evaluation. Only present if the payment is denied by Circle's risk service. properties: decision: description: Enumerated decision of the account. type: string enum: - approved - denied - review reason: description: Risk reason for the definitive decision outcome. type: - string - 'null' example: '3000' FinalAdjustments: type: - object - 'null' description: >- Final adjustment which increases (credits) or decreases (debits) the total returned amount to the source wallet. properties: fxCredit: $ref: '#/components/schemas/FiatMoneyUsd' fxDebit: $ref: '#/components/schemas/FiatMoneyUsd' UnwithdrawalObject: type: - object - 'null' description: >- Return information if the payout is returned by the bank. Only present if `errorCode` of payout is `transaction_returned`. properties: id: $ref: '#/components/schemas/Id' payoutId: type: string description: >- Universally unique identifier (UUID v4) of the payout that is associated with the return. format: uuid example: abdb500d-4a59-457c-801f-2d418c8703ac amount: $ref: '#/components/schemas/FiatMoneyUsd' fees: $ref: '#/components/schemas/FiatMoneyUsd' reason: type: string description: Reason for the return. example: payout_returned status: type: string description: Status of the return. enum: - pending - complete - failed createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' SubAccountSweep: type: object description: Withdrawal details for a single sub-account. properties: subAccountId: type: string description: Identifier of the sub-account. amount: $ref: '#/components/schemas/Money' status: $ref: '#/components/schemas/BurnAllSweepJobState' UtcTimestamp: type: string description: ISO-8601 UTC date/time format. example: '2020-04-10T02:13:30.000Z' ErrorDetail: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. example: invalid_value location: type: string description: Query parameter or request field that caused the error. example: assetType message: type: string description: Human-readable description of the specific error. example: The operation and assetType combination is invalid. Money: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: type: string description: Currency code for the amount. example: USD enum: - USD - EUR BurnAllSweepJobState: type: string description: Status of the sub-account withdrawal. enum: - pending - complete - failed - skipped headers: XRequestId: description: > Circle-generated universally unique identifier (UUID v4). Useful for identifying a specific request when communicating with Circle Support. schema: $ref: '#/components/schemas/XRequestId' responses: BadRequest: description: The request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 2 message: API parameter invalid. NotAuthorized: description: >- The request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 4 message: Unauthorized. ScaForbidden: description: | The SCA assertion failed. Possible error codes: | Code | Meaning | |--------|-----------------------------------------------------| | 420046 | Assertion signature invalid | | 420047 | Intent does not match the operation request body | | 420063 | Challenge was issued for a different clientEntityId | | 420064 | Application origin is not registered for SCA | content: application/json: schema: $ref: '#/components/schemas/Error' ScaChallengeNotFound: description: > SCA challenge not found (error code 420061). The `challengeId` in `X-Sca-Challenge-Id` does not exist or belongs to a different distributor. Open a new challenge and retry. content: application/json: schema: $ref: '#/components/schemas/Error' ScaChallengeExpired: description: | SCA challenge expired or already consumed. Possible error codes: | Code | Meaning | |--------|------------------------------------------------| | 420054 | Challenge expired (5-minute TTL) | | 420055 | Challenge already consumed | Open a new challenge and retry. content: application/json: schema: $ref: '#/components/schemas/Error' RequestTooLarge: description: | The request body or the `X-Sca-Assertion` or `X-Sca-Challenge-Id` header is too large to process (error code 420067). A request built from valid field values is always within the limit, so check the body and headers for an oversized or unexpected value. Retrying the same request returns the same error. content: application/json: schema: $ref: '#/components/schemas/Error' ScaRequired: description: | The `X-Sca-Challenge-Id` or `X-Sca-Assertion` header is missing (error code 420058). Include both headers and retry. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: >- The server encountered an unexpected condition that prevented it from fulfilling the request. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1 message: 'Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4' ScaUnavailable: description: | SCA scope could not be resolved (error code 420059). The legal-entity lookup service (CDS) is unavailable and no prior resolution exists for this entity. Retry after a short delay. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````