> ## 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 a payout > Create a stablecoin payout. The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts: | amount.currency | toAmount.currency | | ---------------- | ----------------- | | USD | USD | | EUR | EUR | Required fields depend on your Circle entity; use the request body options that match your integration. For Singapore (CIRCLE_SG) entities and customers using Managed Payments, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`. ## OpenAPI ````yaml openapi/payouts.yaml post /v1/payouts openapi: 3.0.2 info: version: ${version} title: Crypto Payouts API description: >- The Circle Payouts API allows you to programmatically make fast, global payouts to your customers, vendors, and suppliers. Make payouts on supported blockchains. servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Payouts description: Create and get information on address book payouts. - name: Crypto Address Book description: Manage blockchain addresses with metadata. paths: /v1/payouts: post: tags: - Payouts summary: Create a payout description: > Create a stablecoin payout. The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts: | amount.currency | toAmount.currency | | ---------------- | ----------------- | | USD | USD | | EUR | EUR | Required fields depend on your Circle entity; use the request body options that match your integration. For Singapore (CIRCLE_SG) entities and customers using Managed Payments, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`. operationId: createPayout requestBody: content: application/json: schema: oneOf: - title: General customers description: For Circle entities other than CIRCLE_SG. allOf: - $ref: '#/components/schemas/CryptoPayoutCreationRequest' - title: FR customers description: >- For France (CIRCLE_FR) entities. The request shape matches General customers; the legal entity identifier (LEI) is supplied on the address book recipient via `identity.lei`, not on the payout. allOf: - $ref: '#/components/schemas/CryptoPayoutCreationRequest' - title: SG customers description: >- For Singapore (CIRCLE_SG) entities and customers using Managed Payments. `purposeOfTransfer` is required. allOf: - $ref: '#/components/schemas/CryptoPayoutCreationRequest' - type: object required: - purposeOfTransfer properties: purposeOfTransfer: $ref: '#/components/schemas/CryptoPayoutPurposeOfTransfer' - title: Managed Payments fiat payout description: > For Managed Payments entities sending fiat payouts to a registered beneficiary. Set `destination.type` to `fiat_address_book` and supply a locked quote from `POST /v1/payouts/quotes`. The beneficiary must be in `ACTIVE` status. type: object required: - idempotencyKey - destination - amount - quoteId - useCase - reasonForPayment - customerRefId properties: idempotencyKey: $ref: '#/components/schemas/IdempotencyKey' source: type: object properties: type: type: string enum: - wallet id: type: string description: >- Wallet ID to debit. Defaults to the entity master wallet. example: '1000000001' destination: type: object required: - type - id properties: type: type: string enum: - fiat_address_book id: type: string format: uuid description: >- Beneficiary UUID from `POST /v1/beneficiaries`. Must be `ACTIVE`. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 amount: type: object required: - amount - currency properties: amount: type: string description: >- Amount in source currency. Must match the `from.amount` on the quote. example: '95.50' currency: type: string description: Source cryptocurrency (e.g. `USDC`, `EURC`). example: USDC quoteId: type: string format: uuid description: > Locked quote identifier from `POST /v1/payouts/quotes`. Quotes expire at `expiresAt`; submitting an expired quote returns a `400`. example: 66666666-7777-8888-9999-000000000000 useCase: type: string enum: - B2B - B2C - C2B - C2C description: > Use case describing the originator and recipient relationship. - `B2B` — business originator, business recipient. - `B2C` — business originator, individual recipient. - `C2B` — individual originator, business recipient. - `C2C` — individual originator, individual recipient. example: B2C reasonForPayment: type: string description: > Payment reason code. See [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). example: PMT001 customerRefId: type: string description: Customer-provided reference identifier for this payout. example: order-9876 originatorMode: type: integer description: > Travel rule originator nesting mode. `0` = standalone (default), `1` = nested (originator is acting on behalf of another party). default: 0 example: 0 travelRule: type: object description: > Originator travel rule information. Required fields depend on `originatorMode` and the destination corridor. Keys match the field names returned by `GET /v1/beneficiaries/requirements`. additionalProperties: true example: ORIGINATOR_NAME: Acme Corp ORIGINATOR_ADDRESS: STREET: 1 Main St CITY: New York STATE_PROVINCE: NY POSTAL_CODE: '10001' COUNTRY: US responses: '201': description: Successfully created a payout. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: title: CreatePayoutResponse properties: data: $ref: '#/components/schemas/CryptoPayoutResponseData' examples: Fiat Payout (Managed Payments): value: data: id: f1e2d3c4-b5a6-7890-abcd-ef0987654321 sourceWalletId: '1000000001' destination: type: fiat_address_book id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 amount: amount: '95.50' currency: USDC quoteId: 66666666-7777-8888-9999-000000000000 useCase: B2C reasonForPayment: PMT001 customerRefId: order-9876 status: pending createDate: '2026-08-12T00:10:00.000Z' updateDate: '2026-08-12T00:10:00.000Z' Crypto Payout: value: data: id: b8627ae8-732b-4d25-b947-1df8f4007a29 sourceWalletId: '53535335' destination: type: address_book id: b8627ae8-732b-4d25-b947-1df8f4007a29 amount: amount: '3.14' currency: USD toAmount: amount: '3.14' currency: ETH fees: amount: '3.14' currency: USD networkFees: amount: '0.14' currency: USD purposeOfTransfer: PMT001 customerExternalRef: customer-ref-123 status: pending errorCode: transaction_denied riskEvaluation: decision: denied reason: '4000' createDate: '2020-04-10T02:13:30.000Z' updateDate: '2020-04-10T02:13:30.000Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' security: - bearerAuth: [] components: schemas: CryptoPayoutCreationRequest: type: object required: - idempotencyKey - destination - amount properties: idempotencyKey: $ref: '#/components/schemas/IdempotencyKey' source: $ref: '#/components/schemas/TransferSourceWalletLocation' destination: $ref: '#/components/schemas/CryptoPayoutDestination' amount: $ref: '#/components/schemas/CryptoPayoutMoney' toAmount: $ref: '#/components/schemas/CryptoPayoutMoney' purposeOfTransfer: $ref: '#/components/schemas/CryptoPayoutPurposeOfTransfer' metadata: $ref: '#/components/schemas/MetadataCryptoPayout' CryptoPayoutPurposeOfTransfer: type: string description: > Payment reason code for the payout. Aligned with Circle payment reason codes for Crypto Payouts. Do not use `PMT006`. See [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid values can return error code `5020`. enum: - PMT000 - PMT001 - PMT002 - PMT003 - PMT004 - PMT005 - PMT007 - PMT008 - PMT009 - PMT010 - PMT011 - PMT012 - PMT013 - PMT014 - PMT015 - PMT016 - PMT017 - PMT018 - PMT019 - PMT020 - PMT021 - PMT022 - PMT023 - PMT024 - PMT025 - PMT026 - PMT027 - PMT028 - PMT029 - PMT030 example: PMT001 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 CryptoPayoutResponseData: description: > Payout resource returned by create and get operations. Includes `purposeOfTransfer` when it was provided at create time (required for CIRCLE_SG entities). allOf: - $ref: '#/components/schemas/CryptoPayoutResponseGeneral' - type: object properties: purposeOfTransfer: $ref: '#/components/schemas/CryptoPayoutPurposeOfTransfer' TransferSourceWalletLocation: description: A source wallet location. type: object required: - type - id properties: type: type: string enum: - wallet id: type: string description: The id of the wallet. example: '12345' identities: type: array items: $ref: '#/components/schemas/Identity' useMainWalletFunding: type: boolean description: > When true, if the designated source wallet lacks sufficient funds for the payout, funds are transferred from the master wallet to the source wallet before the payout executes. For Managed Payments customers only. Default is true. CryptoPayoutDestination: type: object description: The destination. required: - type - id properties: type: $ref: '#/components/schemas/CryptoPayoutDestinationType' id: $ref: '#/components/schemas/Id' CryptoPayoutMoney: type: object required: - amount - currency properties: amount: type: string description: > The numeric value of the amount, expressed in units of the specified currency. Use a period (`.`) as the decimal separator. example: '3.14' currency: type: string description: The ISO 4217 currency code for the amount. enum: - USD - EUR MetadataCryptoPayout: type: object description: Additional properties related to the crypto payout. properties: customerExternalRef: $ref: '#/components/schemas/CustomerExternalRef' description: Customer-supplied reference to reconcile transactions. CryptoPayoutResponseGeneral: type: object properties: id: $ref: '#/components/schemas/Id' sourceWalletId: type: string description: The identifier of the source wallet used to fund a payout. example: '53535335' destination: $ref: '#/components/schemas/CryptoPayoutDestination' amount: $ref: '#/components/schemas/PayoutMoney' toAmount: $ref: '#/components/schemas/PayoutMoney' fees: $ref: '#/components/schemas/PayoutMoney' networkFees: $ref: '#/components/schemas/PayoutMoney' customerExternalRef: $ref: '#/components/schemas/CustomerExternalRef' description: Customer-supplied reference to reconcile transactions. status: $ref: '#/components/schemas/PayoutStatus' errorCode: $ref: '#/components/schemas/PayoutErrorCode' riskEvaluation: $ref: '#/components/schemas/RiskEvaluation' createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' Identity: type: object description: | The identity of the originator. Identities are required when: * `destination.type: "blockchain"` * `destination.chain: "ETH"` * `amount.amount` >= $3,000 in value required: - type - name - addresses properties: type: type: string description: > The type of identity for the originator. * `individual` - A uniquely distinguishable individual. * `business` - Any entity other than a natural person that can establish a permanent customer relationship with an affected entity or otherwise own property. This can include companies, foundations, anstalt, partnerships, associations and other relevantly similar entities. enum: - individual - business name: type: string description: Full name of the identity. example: Satoshi Nakamoto maxLength: 1024 addresses: type: array items: $ref: '#/components/schemas/IdentityAddress' CryptoPayoutDestinationType: type: string description: The destination type. enum: - address_book Id: type: string description: Unique system generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 CustomerExternalRef: type: string description: A customer-supplied reference for reconciliation purposes. pattern: ^[A-Za-z0-9-]{1,21}$ example: INV-2024-001234 PayoutMoney: 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: ISO 4217 alpha-3 currency code for the amount. pattern: ^[A-Z]{3}$ example: 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 nullable: true description: >- Indicates the failure reason of a payout. Only present for payouts in failed state. Possible values are [`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`]' 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 RiskEvaluation: type: object description: >- Results of risk evaluation. Present when the payment's risk decision is `denied` or `review`. Absent when `decision` is `approved` or when no risk evaluation was performed. nullable: true properties: decision: description: Enumerated decision of the account. type: string enum: - approved - denied - review reason: description: >- Risk reason code for the decision. Known values include `3000` (transaction involves a sanctioned or unsupported wallet) and `2151` (transaction denied on outbound compliance screening; a failed refund, for example). Present when `decision` is `denied`; may be omitted for `review` decisions. type: string nullable: true example: '3000' UtcTimestamp: type: string description: ISO-8601 UTC date/time format. example: '2020-04-10T02:13:30.000Z' IdentityAddress: type: object required: - line1 - city - district - postalCode - country properties: line1: type: string description: Line one of the street address. maxLength: 1024 example: 100 Money Street line2: type: string description: Line two of the street address. maxLength: 1024 example: Suite 1 city: type: string description: City portion of the address. maxLength: 1024 example: Boston district: description: >- State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision. type: string maxLength: 16 example: MA postalCode: type: string description: Postal / ZIP code of the address. maxLength: 16 example: '01234' country: type: string description: >- Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: US headers: XRequestId: description: >- Universally unique identifier (UUID v4) for the request. Helpful for identifying a request when communicating with Circle support. schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde 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: type: object title: BadRequest required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 400 message: Bad request. examples: response: value: code: 400 message: Bad request. 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: type: object title: NotAuthorized required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 401 message: Malformed authorization. examples: response: value: code: 401 message: Malformed authorization. securitySchemes: bearerAuth: type: http scheme: bearer ````