openapi: 3.1.0 info: title: Coinbase Developer Platform APIs description: >- The Coinbase Developer Platform APIs - leading the world's transition onchain. license: name: MIT url: https://opensource.org/licenses/MIT version: 2.0.0 contact: name: Coinbase Developer Platform email: cdp@coinbase.com url: https://cdp.coinbase.com servers: - url: https://api.cdp.coinbase.com/platform description: The production server of the CDP APIs. security: - apiKeyAuth: [] tags: - name: Accounts x-audience: public x-slo-tier: tier: beta description: >- The Accounts APIs enable developers to create and manage accounts for their Entity. An Account is a container that holds assets and can be used for transacting. Accounts can be of different types including entity accounts, prime accounts, and business accounts. Support for Customer-owned accounts is in development. - name: Deposit Destinations x-audience: public x-slo-tier: tier: beta description: >- Deposit Destinations allow you to manage where funds can be deposited into your accounts. ## Crypto Deposit Destinations Crypto deposit destinations are cryptocurrency addresses that you can generate and fetch via the API. Once created, these addresses can receive cryptocurrency payments on their specified network and will settle in your account balance. **Metadata:** You can attach metadata to any deposit destination you create to track the purpose or source of deposits. **Example:** ```json { "depositDestinationId": "depositDestination_123", "accountId": "account_456", "type": "crypto", "crypto": { "network": "base", "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "target": { "accountId": "account_789", "asset": "usd" }, "status": "active", "metadata": { "customer_id": "cust_789", "reference": "order-12345" } } ``` Use the list endpoint to retrieve all deposit destinations. - name: Payment Acceptance (Under Development) x-audience: development description: >- Payment Acceptance enables merchants to accept commercial payments on-chain. It handles the full lifecycle of a payment — authorization, capture, void, and refund — driven by a central payment session that tracks state and balances at every step. - name: Payment Methods x-audience: public x-slo-tier: tier: beta description: >- The Payment Methods APIs enable you to create and manage payment methods for accounts. Payment methods represent ways to send and receive payments, such as ACH transfers and Fedwire transfers. These APIs allow you to create, list, and retrieve payment method details for use in payment transfers and transactions. - name: Transfers x-audience: public x-slo-tier: tier: beta description: >- **Transfers** represent both the request and execution of fund transfers from a source to a target. They provide upfront fee quotes and track the complete lifecycle from initiation through completion, failure, or reversal. ## Fee Quotes Every transfer provides a comprehensive fee quote in the `fees` array. This allows you to show users exactly what they'll pay before any money moves. To review fees before execution: 1. Create a transfer with `execute: false` 2. Review the `fees` array in the response 3. Call `POST /transfers/{transferId}/execute` when ready to proceed For automatic execution without fee review, create a transfer with `execute: true`. **Fee Expiration**: Fee quotes are valid for a limited time (typically 10-15 minutes from creation). The `expiresAt` field shows exactly when the fee quote will expire. If you don't execute before this time, you'll need to create a new transfer to get updated fees. ## Fees Transfer fees vary by source, target, amount and transfer type: * **Bank fees** - Traditional banking fees for depositing funds (e.g., $15.00 wire transfer fee) * **Conversion fees** - Fees for exchanging between different assets * **Network fees** - Onchain transaction costs to complete the transfer (e.g., ETH gas fees) All fees are disclosed upfront in the `fees` array when you create a transfer. ## Transfer Lifecycle When you create a transfer, it will be in one of these statuses that determine what action you need to take: * **`quoted`** - Transfer is ready but requires manual execution via the `/execute` endpoint * **`processing`** - Transfer is being executed (no action needed - poll for completion) * **`completed`** - Transfer completed successfully * **`failed`** - Transfer failed (see `failureReason` for details) ## Execution Control * **`execute: true`**: Transfer will automatically attempt to execute * **`execute: false`**: Transfer will be created in `quoted` status and you must call the `/execute` endpoint. Use this to obtain a fee quote or validate a transfer destination before deciding whether to execute the Transfer. ## Sources and Targets * A **source** can be an Account or a Payment Method * A **target** can be an Account, Payment Method, Onchain Address, or Email Address ## Transfer Execution When a transfer reaches `completed` status, it contains the final execution details that delivered funds to the target and completion timestamps. ## Failure Reasons When a transfer fails, the `failureReason` field provides a human-readable description of what went wrong. Common failure reasons include: * "Insufficient balance to complete this transfer." * "The recipient address is invalid for the selected network." * "The recipient address failed security validation checks." * "Unable to send to this recipient." Failure reason is only present when the transfer's status is `failed`. - name: Webhooks x-audience: public x-slo-tier: tier: ga description: >- Subscribe to real-time events across CDP products. Monitor onchain activity on Base mainnet, track onramp/offramp transactions, and receive instant notifications for wallet events. paths: /v2/accounts: get: summary: List accounts description: >- List all accounts. The API will return all accounts that the API Key has Permissions to access. You can filter the results by using query parameters, which will be treated as a single conjunction (i.e. AND). Results are sorted by creation date in descending order (newest first). operationId: listFoundationAccounts tags: - Accounts security: - apiKeyAuth: [] - sessionAuth: [] x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any parameters: - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' - name: type in: query required: false description: >- Filter accounts by account type. When omitted, accounts of any type are returned. Combined with `owner` using AND. schema: $ref: '#/components/schemas/AccountType' example: prime responses: '200': description: Successfully listed accounts. content: application/json: schema: allOf: - type: object required: - accounts properties: accounts: type: array description: The list of accounts. items: $ref: '#/components/schemas/Account' - $ref: '#/components/schemas/ListResponse' examples: entity_owned: summary: Account owned by your Entity value: accounts: - accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: prime owner: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 name: My Business Account createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. post: summary: Create account description: >- Create an account for your Entity. Support for creating Customer-owned accounts is in development. operationId: createFoundationAccount tags: - Accounts security: - apiKeyAuth: [] - sessionAuth: [] x-audience: public x-required-permissions: permissions: - accounts:write@entity enforcement: any parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' examples: entity_owned: summary: Create an account owned by your Entity value: name: My Business Account responses: '200': description: Successfully created account. content: application/json: schema: $ref: '#/components/schemas/Account' examples: entity_owned: summary: Account owned by your Entity value: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: cdp owner: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 name: My Business Account createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid account creation request. '403': description: >- Customer is not authorized for one or more capabilities required by this action. content: application/json: schema: $ref: '#/components/schemas/Error' examples: customer_not_authorized: summary: >- Customer is not authorized for one or more required capabilities value: errorType: customer_not_authorized errorMessage: >- Customer is not authorized for one or more capabilities required by this action. unauthorizedCapabilities: - custodyCrypto '422': $ref: '#/components/responses/IdempotencyError' '503': $ref: '#/components/responses/EndpointUnavailableError' /v2/accounts/{accountId}: get: summary: Get account description: Get an account by its ID. operationId: getFoundationAccountById tags: - Accounts security: - apiKeyAuth: [] - sessionAuth: [] x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any parameters: - name: accountId in: path required: true description: The ID of the account to retrieve. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 responses: '200': description: Successfully got account. content: application/json: schema: $ref: '#/components/schemas/Account' examples: entity_owned: summary: Account owned by your Entity value: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: prime owner: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 name: My Business Account createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid account ID. '404': description: Account not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Account not found. /v2/accounts/{accountId}/balances: get: summary: List balances for account description: >- List the balances for an account. Results are sorted by native-fiat equivalent balance in descending order. operationId: listBalances tags: - Accounts security: - apiKeyAuth: [] - sessionAuth: [] x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any parameters: - name: accountId in: path required: true description: The unique identifier of the account. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed balances. content: application/json: schema: allOf: - $ref: '#/components/schemas/Balances' - $ref: '#/components/schemas/ListResponse' example: balances: - asset: symbol: btc type: crypto name: Bitcoin decimals: 8 amount: btc: available: '2.5' total: '3.0' usd: available: '252705.4' total: '303246.48' - asset: symbol: usd type: fiat name: United States Dollar decimals: 2 amount: usd: available: '90' total: '100' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid account ID or query parameters. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: Authentication required. '404': description: Account not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Account not found. '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: errorType: internal_server_error errorMessage: An internal server error occurred. '503': $ref: '#/components/responses/EndpointUnavailableError' /v2/accounts/{accountId}/balances/{asset}: get: summary: Get balance for account description: Get the balance for an account by asset. operationId: getBalanceByAsset tags: - Accounts security: - apiKeyAuth: [] - sessionAuth: [] x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any parameters: - name: accountId in: path required: true description: The unique identifier of the account. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - name: asset in: path required: true description: The symbol of the asset. schema: $ref: '#/components/schemas/Asset' example: btc responses: '200': description: Successfully got balance. content: application/json: schema: $ref: '#/components/schemas/Balance' example: asset: symbol: btc type: crypto name: Bitcoin decimals: 8 amount: btc: available: '2.5' total: '3.0' usd: available: '252705.4' total: '303246.48' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid account ID or asset symbol. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: Authentication required. '404': description: Account or asset not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Account or asset not found. '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: errorType: internal_server_error errorMessage: An internal server error occurred. '503': $ref: '#/components/responses/EndpointUnavailableError' /v2/coinbase-accounts/balances: get: summary: List Coinbase account balances description: >- Returns the balances held in the Coinbase account. The `available` amount is the immediately spendable balance. The `total` amount also includes funds currently on hold. Both amounts are returned as decimal strings with 2 decimal places (e.g. `"50.00"`). **Authentication:** Requires a Coinbase OAuth Bearer token with the `coinbase:stablecoins:balance-read` scope. **Returned assets:** Currently always returns a single USDC entry. If the payer holds no USDC, the entry is still returned with an `available` and `total` of `"0"` so callers do not need to special-case a missing asset. Additional assets may be returned in the future without a contract change. operationId: listCoinbaseAccountBalances x-audience: development tags: - Payment Acceptance (Under Development) security: - oauth: [] responses: '200': description: Successfully retrieved Coinbase account balances. content: application/json: schema: $ref: '#/components/schemas/Balances' examples: with_balance: summary: Payer holds USDC value: balances: - asset: symbol: usdc type: crypto name: USD Coin decimals: 6 amount: usdc: available: '50.00' total: '100.00' zero_balance: summary: Payer holds no USDC value: balances: - asset: symbol: usdc type: crypto name: USD Coin decimals: 6 amount: usdc: available: '0.00' total: '0.00' '401': $ref: '#/components/responses/UnauthorizedError' '403': description: >- The bearer token is valid but lacks the required `coinbase:stablecoins:balance-read` OAuth scope, or was minted from a CDP API key rather than an OAuth session. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_scope: summary: Bearer token is missing the required OAuth scope value: errorType: forbidden errorMessage: >- The bearer token does not have the required OAuth scope: coinbase:stablecoins:balance-read. wrong_auth_type: summary: Bearer token was minted from a CDP API key value: errorType: forbidden errorMessage: >- This endpoint requires a Coinbase OAuth bearer token; CDP API key tokens are not accepted. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/deposit-destinations: get: summary: List deposit destinations description: >- List deposit destinations. You can optionally filter the results by type, account ID, network, or cryptocurrency address. Results are sorted by creation date in descending order (newest first). operationId: listDepositDestinations x-audience: public x-required-permissions: permissions: - accounts:read@entity - accounts:read@project enforcement: any tags: - Deposit Destinations security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: accountId in: query required: false description: Filter deposit destinations by account ID. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - name: address in: query required: false description: Filter deposit destinations by the cryptocurrency address. schema: type: string description: >- The cryptocurrency address to filter by. Format depends on the network (e.g., 0x-prefixed for EVM networks, base58 for Solana). example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' - name: type in: query required: false description: Filter deposit destinations by type. schema: $ref: '#/components/schemas/DepositDestinationType' example: crypto - name: network in: query required: false description: Filter deposit destinations by network. schema: type: string description: >- The blockchain network to filter by (e.g., base, ethereum). Only applies to crypto deposit destinations. example: base - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed deposit destinations. content: application/json: schema: allOf: - type: object required: - depositDestinations properties: depositDestinations: type: array description: The list of deposit destinations. items: $ref: '#/components/schemas/DepositDestination' - $ref: '#/components/schemas/ListResponse' examples: crypto: summary: Crypto deposit destination value: depositDestinations: - depositDestinationId: >- depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' crypto: network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd status: active metadata: customer_id: 123e4567-e89b-12d3-a456-426614174000 reference: order-12345 createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: Authentication required. '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: errorType: internal_server_error errorMessage: An internal server error occurred. post: summary: Create deposit destination description: >- Create a new deposit destination for an account. A deposit destination is a cryptocurrency address that can be used to receive funds. The address will be generated for the specified network. operationId: createDepositDestination x-audience: public x-required-permissions: permissions: - accounts:write@entity enforcement: any tags: - Deposit Destinations security: - apiKeyAuth: [] - sessionAuth: [] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDepositDestinationRequest' examples: crypto: summary: Create a crypto deposit destination value: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto crypto: network: base target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd metadata: customer_id: 123e4567-e89b-12d3-a456-426614174000 reference: order-12345 responses: '201': description: Successfully created deposit destination. content: application/json: schema: $ref: '#/components/schemas/DepositDestination' examples: crypto: summary: Crypto deposit destination value: depositDestinationId: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' crypto: network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd status: active metadata: customer_id: 123e4567-e89b-12d3-a456-426614174000 reference: order-12345 createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid network specified or missing required fields. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: Authentication required. '403': description: >- Customer is not authorized for one or more capabilities required by this action. content: application/json: schema: $ref: '#/components/schemas/Error' examples: customer_not_authorized: summary: >- Customer is not authorized for one or more required capabilities value: errorType: customer_not_authorized errorMessage: >- Customer is not authorized for one or more capabilities required by this action. unauthorizedCapabilities: - custodyCrypto '404': description: Account not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Account not found. '422': $ref: '#/components/responses/IdempotencyError' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: errorType: internal_server_error errorMessage: An internal server error occurred. '503': $ref: '#/components/responses/EndpointUnavailableError' /v2/deposit-destinations/{depositDestinationId}: get: summary: Get deposit destination description: Get a specific deposit destination by its ID. operationId: getDepositDestinationById x-audience: public x-required-permissions: permissions: - accounts:read@entity - accounts:read@project enforcement: any tags: - Deposit Destinations security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: depositDestinationId in: path required: true description: The ID of the deposit address to retrieve. schema: $ref: '#/components/schemas/DepositDestinationId' example: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 responses: '200': description: Successfully retrieved deposit destination. content: application/json: schema: $ref: '#/components/schemas/DepositDestination' examples: crypto: summary: Crypto deposit destination value: depositDestinationId: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' crypto: network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd status: active metadata: customer_id: 123e4567-e89b-12d3-a456-426614174000 reference: order-12345 createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid deposit address ID. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: Authentication required. '404': description: Deposit address not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Deposit address not found. '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: value: errorType: internal_server_error errorMessage: An internal server error occurred. /v2/transfers: post: summary: Create transfer description: >- Create a new transfer to move funds from a source to a target. All transfers first transition to `quoted`. If `execute: false`, the transfer stays quoted until you call `/v2/transfers/{transferId}/execute`. If `execute: true`, quoted status emits momentarily before the transfer moves to `processing`, where execution proceeds. Subscribe to the transfers webhook to follow progress in real time instead of polling. operationId: createTransfer x-audience: public x-required-permissions: permissions: - transfers:write@entity enforcement: any tags: - Transfers security: - apiKeyAuth: [] - sessionAuth: [] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/TransferRequest' example: source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base asset: usdc amount: '100.00' asset: usd execute: false validateOnly: false metadata: invoiceId: '12345' reference: 'Payment for invoice #12345' travelRule: isSelf: false isIntermediary: true originator: name: John Doe address: line1: 123 Main St line2: Unit 201 city: San Francisco state: California postCode: '94105' countryCode: US financialInstitution: PayPal, Inc. vaspName: Fidelity Digital Asset Services, LLC vaspAddress: line1: 123 Market St line2: Suite 400 city: San Francisco state: California postCode: '94105' countryCode: US vaspIdentifier: 5493001KJTIIGC8Y1R17 personalIdentification: type: social_security_number value: 123-45-6789 countryOfIssue: US dateOfBirth: day: '15' month: '08' year: '1990' beneficiary: name: Jane Smith address: line1: 456 Oak Ave city: Paris postCode: '75001' countryCode: FR walletType: custodial responses: '200': description: Successfully created transfer. content: application/json: schema: $ref: '#/components/schemas/Transfer' examples: regular: $ref: '#/components/examples/RegularTransferQuoted' fx_quoted: $ref: '#/components/examples/FxTransferQuoted' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '403': description: >- Customer is not authorized for one or more capabilities required by this action. content: application/json: schema: $ref: '#/components/schemas/Error' examples: customer_not_authorized: summary: >- Customer is not authorized for one or more required capabilities value: errorType: customer_not_authorized errorMessage: >- Customer is not authorized for one or more capabilities required by this action. unauthorizedCapabilities: - transferStablecoin - tradeStablecoin - tradeCrypto - custodyStablecoin '422': $ref: '#/components/responses/IdempotencyError' get: summary: List transfers description: >- List transfers for your organization. Use this to view and monitor your transfer activity. **Status Filtering**: Filter by specific status to efficiently manage transfers: * `?status=processing` - Monitor active transfers. * `?status=quoted` - Find transfers awaiting execution. * `?status=failed` - Review failed transfers for troubleshooting. * `?status=completed` - Find completed transfers. **Account Filtering**: Filter by account ID to find transfers involving a specific account: * `?accountId=` - All transfers where the account is either source or target (OR semantics). * `?sourceAccountId=` - Only transfers where the account is the source (outbound). * `?targetAccountId=` - Only transfers where the account is the target (inbound). Providing `accountId` together with `sourceAccountId` or `targetAccountId` is a validation error and returns HTTP 400. **Date Range Filtering**: Filter by creation or last-updated time for reconciliation: * `?createdAfter=2026-01-01T00:00:00Z&createdBefore=2026-01-31T23:59:59Z` - Transfers created within a date range. * `?updatedAfter=2026-01-01T00:00:00Z` - Transfers updated since a given time. Useful for incremental sync. **Asset Filtering**: Filter by source or target asset symbol: * `?sourceAsset=usd` - Transfers funded from a USD account. * `?targetAsset=usdc` - Transfers delivering USDC to the target. **Other Filters**: * `?sourceAddress=0x...` - Transfers from a specific on-chain source address. * `?targetAddress=0x...` - Transfers to a specific on-chain destination address. * `?targetEmail=user@example.com` - Transfers to a specific email recipient. * `?transferId=transfer_...` - Look up a single transfer by ID; bypasses pagination. operationId: listTransfers x-audience: public x-required-permissions: permissions: - transfers:read@entity - transfers:read@project enforcement: any tags: - Transfers security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: status in: query required: false description: >- Filter transfers by status. Useful for building dashboards, monitoring active transfers, or finding transfers needing action. example: quoted schema: $ref: '#/components/schemas/TransferStatus' - name: accountId in: query required: false description: >- Filter transfers by account ID. Returns transfers where the specified account is either the source or target (OR semantics). Cannot be combined with `sourceAccountId` or `targetAccountId`. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - name: sourceAccountId in: query required: false description: >- Filter transfers by source account ID. Returns only transfers where the specified account is the source. Cannot be combined with `accountId`. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - name: targetAccountId in: query required: false description: >- Filter transfers by target account ID. Returns only transfers where the specified account is the target. Cannot be combined with `accountId`. schema: $ref: '#/components/schemas/AccountId' example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - name: createdAfter in: query required: false description: >- Filter transfers to those created at or after this datetime (inclusive). ISO 8601 format. example: '2026-01-01T00:00:00Z' schema: type: string format: date-time - name: createdBefore in: query required: false description: >- Filter transfers to those created at or before this datetime (inclusive). ISO 8601 format. example: '2026-01-31T23:59:59Z' schema: type: string format: date-time - name: updatedAfter in: query required: false description: >- Filter transfers to those updated at or after this datetime (inclusive). ISO 8601 format. Useful for incremental sync — poll for transfers that changed state since your last check. example: '2026-01-01T00:00:00Z' schema: type: string format: date-time - name: updatedBefore in: query required: false description: >- Filter transfers to those updated at or before this datetime (inclusive). ISO 8601 format. example: '2026-01-31T23:59:59Z' schema: type: string format: date-time - name: sourceAsset in: query required: false description: Filter transfers by source asset symbol (e.g., `usd`, `usdc`). example: usd schema: type: string - name: targetAsset in: query required: false description: Filter transfers by target asset symbol (e.g., `usdc`, `eth`). example: usdc schema: type: string - name: sourceAddress in: query required: false description: Filter transfers by the on-chain address of the source. example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' schema: $ref: '#/components/schemas/BlockchainAddress' - name: targetAddress in: query required: false description: Filter transfers by the on-chain destination address of the target. example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' schema: $ref: '#/components/schemas/BlockchainAddress' - name: targetEmail in: query required: false description: Filter transfers by the email address of the target recipient. example: recipient@example.com schema: $ref: '#/components/schemas/Email' - name: transferId in: query required: false description: >- Filter to a specific transfer by ID. When provided, returns only the matching transfer and bypasses pagination. example: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 schema: type: string pattern: ^transfer_[a-f0-9\-]{36}$ - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed transfers. content: application/json: schema: allOf: - type: object required: - transfers properties: transfers: type: array description: The list of transfers. items: $ref: '#/components/schemas/Transfer' - $ref: '#/components/schemas/ListResponse' examples: page: $ref: '#/components/examples/ListTransfersResponse' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. /v2/transfers/{transferId}: get: summary: Get transfer description: Get a transfer by its ID. operationId: getTransferById x-audience: public x-required-permissions: permissions: - transfers:read@entity - transfers:read@project enforcement: any tags: - Transfers security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: transferId in: path required: true description: The unique identifier of the transfer. schema: type: string pattern: ^transfer_[a-f0-9\-]{36}$ example: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 responses: '200': description: Successfully got transfer. content: application/json: schema: $ref: '#/components/schemas/Transfer' examples: regular: $ref: '#/components/examples/RegularTransferQuoted' fx_quoted: $ref: '#/components/examples/FxTransferQuoted' fx_completed: $ref: '#/components/examples/FxTransferCompleted' '404': description: Transfer not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: summary: Transfer not found value: errorType: not_found errorMessage: Transfer not found. /v2/transfers/{transferId}/execute: post: x-audience: public x-required-permissions: permissions: - transfers:write@entity enforcement: any summary: Execute transfer description: >- Executes a transfer which was created using the Create a transfer endpoint. operationId: executeFundTransfer tags: - Transfers security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: transferId description: The ID of the transfer. in: path required: true schema: type: string pattern: ^transfer_[a-f0-9\-]{36}$ example: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Successfully committed a transfer. content: application/json: schema: $ref: '#/components/schemas/Transfer' example: transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: processing source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base asset: usdc amount: '100.00' asset: usd sourceAmount: '103.50' sourceAsset: usd targetAmount: '100.00' targetAsset: usdc exchangeRate: sourceAsset: usd targetAsset: usdc rate: '1' fees: - type: bank amount: '2.50' asset: usd - type: conversion amount: '1.00' asset: usd executedAt: '2023-10-08T14:31:00Z' createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:31:00Z' metadata: invoiceId: '12345' reference: 'Payment for invoice #12345' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid transfer ID. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: Authentication error. '403': description: >- Customer is not authorized for one or more capabilities required by this action. content: application/json: schema: $ref: '#/components/schemas/Error' examples: customer_not_authorized: summary: >- Customer is not authorized for one or more required capabilities value: errorType: customer_not_authorized errorMessage: >- Customer is not authorized for one or more capabilities required by this action. unauthorizedCapabilities: - transferStablecoin '404': description: Transfer not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Transfer with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Rate limit exceeded. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/transfers/{transferId}/travel-rule: post: summary: Submit deposit travel rule information description: >- Submit travel rule information for a deposit transfer held pending compliance review. Required fields vary by jurisdiction and may include originator name, address, date of birth, personal ID, and VASP information. If the submitted information satisfies all jurisdictional requirements, `status` will be `completed` and the transfer will proceed. Otherwise, `status` will be `incomplete` and `missingFields` will indicate which fields still need to be provided. operationId: submitDepositTravelRule x-audience: public x-required-permissions: permissions: - transfers:write@entity enforcement: any tags: - Transfers security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: transferId in: path required: true description: The unique identifier of the transfer. schema: type: string pattern: ^transfer_[a-f0-9\-]{36}$ example: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/DepositTravelRuleRequest' example: originator: name: John Doe address: line1: 123 Main St city: San Francisco state: CA postCode: '94105' countryCode: US beneficiary: name: Jane Smith isSelf: false responses: '200': description: Successfully submitted travel rule information. content: application/json: schema: $ref: '#/components/schemas/DepositTravelRuleResponse' examples: incomplete: value: status: incomplete missingFields: - originator.dateOfBirth completed: value: status: completed missingFields: [] '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid request body. '404': description: Transfer not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: summary: Transfer not found value: errorType: not_found errorMessage: Transfer not found. '422': $ref: '#/components/responses/IdempotencyError' /v2/payment-sessions: post: summary: Create a payment session description: >- Creates a payment session that defines what is being paid — amount, asset, and target. Optionally configure execution behavior, expiry deadlines, redirect URLs, and metadata. If expiry deadlines are omitted, sensible defaults are applied (1 day for authorization, 7 days for capture, 30 days for refund). Expiries must be in ascending order — see the `expiries` object for details and constraints. Returns the session in `created` status. Next step: call one of the authorization endpoints (wallet or Coinbase) to authorize the payment. operationId: createPaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentSessionRequest' examples: wallet_target: summary: Payment session with a wallet target value: amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: false externalReferenceId: merchant-order-abc123 wallet_target_with_display: summary: Payment session with merchant-provided display data value: amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: false externalReferenceId: merchant-order-abc123 customerDisplay: merchantName: Acme Store displayAmount: amount: '1.37' currency: cad account_target: summary: Payment session with an account target value: amount: '1.00' asset: usdc target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd autoCapture: false externalReferenceId: merchant-order-abc123 responses: '200': description: Successfully created payment session. content: application/json: schema: $ref: '#/components/schemas/PaymentSession' examples: wallet_target: summary: Payment session created with a wallet target value: paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: created amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '0' refundable: '0' refunded: '0' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad x402Url: >- https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402 externalReferenceId: merchant-order-abc123 metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:00:00.000Z' wallet_target_with_display: summary: Payment session created with merchant-provided display data value: paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: created amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '0' refundable: '0' refunded: '0' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad externalReferenceId: merchant-order-abc123 customerDisplay: merchantName: Acme Store displayAmount: amount: '1.37' currency: cad createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:00:00.000Z' account_target: summary: Payment session created with an account target value: paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: created amount: '1.00' asset: usdc target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '0' refundable: '0' refunded: '0' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad externalReferenceId: merchant-order-abc123 metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:00:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid payment session parameters. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' get: summary: List payment sessions description: >- Returns a paginated list of payment sessions that the API key has permission to access. operationId: listPaymentSessions x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed payment sessions. content: application/json: schema: allOf: - type: object required: - paymentSessions properties: paymentSessions: type: array description: The list of payment sessions. items: $ref: '#/components/schemas/PaymentSession' - $ref: '#/components/schemas/ListResponse' example: paymentSessions: - paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: capture_succeeded amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '1.00' refundable: '1.00' refunded: '0' authorizations: - authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc onchainTransactions: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: '2025-06-15T12:01:00.000Z' updatedAt: '2025-06-15T12:02:00.000Z' captures: - captureId: capture_93d980d2-95f2-55fe-b9d3-2bd340cf10be paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' finalCapture: true onchainTransactions: - transactionHash: >- 0xdef456789012345678901234567890abcdef1234567890abcdef1234567890ab network: base createdAt: '2025-06-15T12:03:00.000Z' updatedAt: '2025-06-15T12:04:00.000Z' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad x402Url: >- https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402 redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success externalReferenceId: merchant-order-abc123 metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:04:00.000Z' - paymentSessionId: paymentSession_a4eaa1f3-c6a4-77f9-d1f5-4df562df32df entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: capture_succeeded amount: '1.00' asset: usdc target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd source: coinbaseUserId: coinbase_user_abc123 autoCapture: true expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '1.00' refundable: '1.00' refunded: '0' authorizations: - authorizationId: authorization_a4eaa1f3-c6a4-77f9-d1f5-4df562df32df paymentSessionId: paymentSession_a4eaa1f3-c6a4-77f9-d1f5-4df562df32df status: succeeded amount: '1.00' source: coinbaseUserId: coinbase_user_abc123 createdAt: '2025-06-15T13:01:00.000Z' updatedAt: '2025-06-15T13:02:00.000Z' captures: - captureId: capture_b5fbb2f4-d7a5-88af-e2f6-5ef673ef43ef paymentSessionId: paymentSession_a4eaa1f3-c6a4-77f9-d1f5-4df562df32df status: succeeded amount: '1.00' finalCapture: true createdAt: '2025-06-15T13:03:00.000Z' updatedAt: '2025-06-15T13:04:00.000Z' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_a4eaa1f3-c6a4-77f9-d1f5-4df562df32df redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success externalReferenceId: merchant-order-def456 metadata: customer_id: cust_67890 order_reference: order-13579 createdAt: '2025-06-15T13:00:00.000Z' updatedAt: '2025-06-15T13:04:00.000Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}: get: summary: Get a payment session description: >- Retrieves a single payment session by its ID, including its current status, balances, and associated metadata. The API key must have permission to access the requested session. operationId: getPaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' responses: '200': description: Successfully retrieved payment session. content: application/json: schema: $ref: '#/components/schemas/PaymentSession' examples: wallet_target: summary: Payment session with a wallet target, authorized via wallet value: paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: authorization_succeeded amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '1.00' captured: '0' refundable: '0' refunded: '0' authorizations: - authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc onchainTransactions: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: '2025-06-15T12:01:00.000Z' updatedAt: '2025-06-15T12:02:00.000Z' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad x402Url: >- https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402 redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success externalReferenceId: merchant-order-abc123 metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:05:00.000Z' account_target: summary: >- Payment session with an account target, authorized via Coinbase value: paymentSessionId: paymentSession_93d980d2-95f2-55fe-b9d3-2bd340cf10be entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: authorization_succeeded amount: '1.00' asset: usdc target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd source: coinbaseUserId: coinbase_user_abc123 autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '1.00' captured: '0' refundable: '0' refunded: '0' authorizations: - authorizationId: authorization_93d980d2-95f2-55fe-b9d3-2bd340cf10be paymentSessionId: paymentSession_93d980d2-95f2-55fe-b9d3-2bd340cf10be status: succeeded amount: '1.00' source: coinbaseUserId: coinbase_user_abc123 createdAt: '2025-06-15T12:01:00.000Z' updatedAt: '2025-06-15T12:02:00.000Z' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_93d980d2-95f2-55fe-b9d3-2bd340cf10be redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success externalReferenceId: merchant-order-def456 metadata: customer_id: cust_67890 order_reference: order-13579 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:05:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: 'Missing required field: paymentSessionId.' '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/cancel: post: summary: Cancel a payment session description: >- Cancels a payment session before any funds have been authorized or captured. The session must be in `created` status. Cancel is blocked while any authorization action is pending. Once canceled, no further actions can be performed on the session. This is the only way to terminate a pre-authorization session — expiry deadlines block actions but do not automatically transition the session to a terminal state. operationId: cancelPaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session to cancel. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CancelPaymentSessionRequest' example: cancellationReason: Customer requested cancellation. responses: '200': description: Successfully canceled payment session. content: application/json: schema: $ref: '#/components/schemas/PaymentSession' examples: wallet_target: summary: Canceled payment session with a wallet target value: paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: canceled amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '0' refundable: '0' refunded: '0' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad x402Url: >- https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402 redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success externalReferenceId: merchant-order-abc123 metadata: customer_id: cust_12345 order_reference: order-67890 cancellationReason: Customer requested cancellation. createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:10:00.000Z' account_target: summary: Canceled payment session with an account target value: paymentSessionId: paymentSession_93d980d2-95f2-55fe-b9d3-2bd340cf10be entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: canceled amount: '1.00' asset: usdc target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' balances: capturable: '0' captured: '0' refundable: '0' refunded: '0' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_93d980d2-95f2-55fe-b9d3-2bd340cf10be redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success externalReferenceId: merchant-order-def456 metadata: customer_id: cust_67890 order_reference: order-13579 cancellationReason: Customer requested cancellation. createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:10:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Payment session cannot be canceled in its current state. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/authorizations/wallet/options: get: summary: Get wallet authorization options description: >- Returns the available wallet authorization options for a payment session. The session must be in `created` status. Provide one or more payer wallet addresses as query parameters. Each option specifies the currency, amount, network, and payloads the payer must sign to authorize the payment. Present the options to the payer and let them choose one, then call **Authorize Wallet** with the selected option. This is a stateless read operation — the session is not modified. If a requested address has no eligible authorization options (e.g. insufficient funds), it appears in `ineligibleAddresses` with a `code` and `message` instead of being absent from `options`. operationId: getWalletAuthorizationOptions x-audience: development tags: - Payment Acceptance (Under Development) security: - unauthenticated: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - name: addresses in: query required: true description: >- The payer wallet addresses to generate authorization options for. Provide between 1 and 5 unique addresses, comma-separated (e.g. `?addresses=0xA,0xB`). Each returned option's `source.address` identifies which requested address it applies to. If a requested address has no eligible authorization options, it appears in `ineligibleAddresses` with a `code` explaining why. schema: type: array items: $ref: '#/components/schemas/BlockchainAddress' minItems: 1 maxItems: 5 uniqueItems: true style: form explode: false example: - '0xAbC1234567890aBcDeF1234567890AbCdEf123456' - '0xDeF9876543210FeDcBa9876543210FedcBa987654' - name: network in: query required: false description: >- Optional filter to restrict options to a specific blockchain network. schema: $ref: '#/components/schemas/PaymentSourceNetwork' example: base - name: asset in: query required: false description: Optional filter to restrict options to a specific asset. schema: $ref: '#/components/schemas/Asset' example: usdc responses: '200': description: Successfully retrieved wallet authorization options. content: application/json: schema: $ref: '#/components/schemas/WalletAuthorizationOptionsResponse' examples: success: summary: Eligible options available for each requested address value: options: - optionId: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc amount: '1.00' asset: usdc network: base payloads: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x1111111111111111111111111111111111111111' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x8f5c2d6f4b9a1e3c7d2f8a6b5c4e3d2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d - optionId: opt_b2c3d4e5-f6a7-8901-bcde-f12345678901 source: address: '0xDeF9876543210FeDcBa9876543210FedcBa987654' network: base asset: usdc amount: '1.00' asset: usdc network: base payloads: - payloadId: payload_bg5160f4-c290-8li1-fjc3-ggg66h379558 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x3333333333333333333333333333333333333333' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b ineligibleAddresses: [] partial: summary: Some requested addresses have no eligible options description: >- The request supplied two payer addresses (`0xAbC1234567890aBcDeF1234567890AbCdEf123456` and `0xDeF9876543210FeDcBa9876543210FedcBa987654`). Only the second holds enough of the session asset on a supported network, so it appears in `options`; the first appears in `ineligibleAddresses` with `code: insufficient_funds`. value: options: - optionId: opt_b2c3d4e5-f6a7-8901-bcde-f12345678901 source: address: '0xDeF9876543210FeDcBa9876543210FedcBa987654' network: base asset: usdc amount: '1.00' asset: usdc network: base payloads: - payloadId: payload_bg5160f4-c290-8li1-fjc3-ggg66h379558 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x3333333333333333333333333333333333333333' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b ineligibleAddresses: - address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' code: insufficient_funds message: The payer does not have sufficient funds. none_eligible: summary: No requested address has an eligible option description: >- No requested payer address holds enough of the session asset on a supported source network to cover the session amount. `options` is empty and every requested address appears in `ineligibleAddresses` with a `code` explaining why. The response is still `200` — the request itself was valid, the result is just an empty set of usable options. value: options: [] ineligibleAddresses: - address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' code: insufficient_funds message: The payer does not have sufficient funds. - address: '0xDeF9876543210FeDcBa9876543210FedcBa987654' code: insufficient_funds message: The payer does not have sufficient funds. '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_addresses: value: errorType: invalid_request errorMessage: At least one wallet address is required. too_many_addresses: value: errorType: invalid_request errorMessage: A maximum of 5 wallet addresses are allowed. duplicate_addresses: value: errorType: invalid_request errorMessage: Duplicate wallet addresses are not allowed. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/authorizations/wallet: post: summary: Authorize a payment session with a wallet description: >- Authorizes a payment session using the payer's wallet. The session must be in `created` status. The `optionId` must match one of the options returned by the **Get Wallet Authorization Options** endpoint. Include the signed payloads for the selected option. On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`. If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization. operationId: authorizeWalletPaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - unauthenticated: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session to authorize. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/WalletAuthorizationRequest' example: optionId: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 signedPayloads: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 signature: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab metadata: customer_id: cust_12345 order_reference: order-67890 responses: '200': description: Successfully created wallet authorization. content: application/json: schema: $ref: '#/components/schemas/Authorization' example: authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: pending amount: '1.00' source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:01:00.000Z' updatedAt: '2025-06-15T12:01:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Payment session cannot be authorized in its current state. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/authorizations/x402: post: summary: Authorize a payment session with x402 description: >- Authorizes a payment session using x402. The session must be in `created` status. The client sends no request body. You may supply the base64-encoded x402-compliant payment payload in the optional **`PAYMENT-SIGNATURE`** header. On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`. **402 Payment Required** may be returned when payment must be supplied before authorization can proceed. The **402** response uses the standard CDP **`Error`** JSON body and may include a **`PAYMENT-REQUIRED`** header (see the **402** response) describing accepted networks, assets, and amounts. If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization. operationId: authorizeX402PaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - unauthenticated: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session to authorize with x402. schema: $ref: '#/components/schemas/PaymentSessionId' - name: PAYMENT-SIGNATURE in: header required: false description: Optional. Base64-encoded (RFC 4648) x402-compliant payment payload. schema: type: string example: >- eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vcHJlbWl1bS1kYXRhIiwiZGVzY3JpcHRpb24iOiJBY2Nlc3MgdG8gcHJlbWl1bSBtYXJrZXQgZGF0YSIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRlZCI6eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJhbW91bnQiOiIxMDAwMCIsImFzc2V0IjoiMHgwMzZDYkQ1Mzg0MmM1NDI2NjM0ZTc5Mjk1NDFlQzIzMThmM2RDRjdlIiwicGF5VG8iOiIweDIwOTY5M0JjNmFmYzBDNTMyOGJBMzZGYUYwM0M1MTRFRjMxMjI4N0MiLCJtYXhUaW1lb3V0U2Vjb25kcyI6NjAsImV4dHJhIjp7Im5hbWUiOiJVU0RDIiwidmVyc2lvbiI6IjIifX0sInBheWxvYWQiOnsic2lnbmF0dXJlIjoiMHgyZDZhNzU4OGQ2YWNjYTUwNWNiZjBkOWE0YTIyN2UwYzUyYzZjMzQwMDhjOGU4OTg2YTEyODMyNTk3NjQxNzM2MDhhMmNlNjQ5NjY0MmUzNzdkNmRhOGRiYmY1ODM2ZTliZDE1MDkyZjllY2FiMDVkZWQzZDYyOTNhZjE0OGI1NzFjIiwiYXV0aG9yaXphdGlvbiI6eyJmcm9tIjoiMHg4NTdiMDY1MTlFOTFlM0E1NDUzODc5MWJEYmIwRTIyMzczZTM2YjY2IiwidG8iOiIweDIwOTY5M0JjNmFmYzBDNTMyOGJBMzZGYUYwM0M1MTRFRjMxMjI4N0MiLCJ2YWx1ZSI6IjEwMDAwIiwidmFsaWRBZnRlciI6IjE3NDA2NzIwODkiLCJ2YWxpZEJlZm9yZSI6IjE3NDA2NzIxNTQiLCJub25jZSI6IjB4ZjM3NDY2MTNjMmQ5MjBiNWZkYWJjMDg1NmYyYWViMmQ0Zjg4ZWU2MDM3YjhjYzVkMDRhNzFhNDQ2MmYxMzQ4MCJ9fX0= - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: >- Successfully created x402 authorization. The **PAYMENT-RESPONSE** header is always included on **200** responses. headers: PAYMENT-RESPONSE: description: >- Always returned on **200**. Base64-encoded (RFC 4648) payload containing the response from the successful payment. schema: type: string example: >- eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4ODU3YjA2NTE5RTkxZTNBNTQ1Mzg3OTFiRGJiMEUyMjM3M2UzNmI2NiJ9 content: application/json: schema: $ref: '#/components/schemas/Authorization' example: authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: pending amount: '1.00' message: Your payment was successfully submitted source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc createdAt: '2025-06-15T12:01:00.000Z' updatedAt: '2025-06-15T12:01:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Payment session cannot be authorized in its current state. '402': $ref: '#/components/responses/PaymentRequired' '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/authorizations/coinbase: post: summary: Authorize a payment session with a Coinbase account description: >- Authorizes a payment session using the payer's Coinbase account authenticated via OAuth. The session must be in `created` status. **Authentication:** Requires a Coinbase OAuth Bearer token with the `coinbase:stablecoins:payment-create` scope. On authorization, a hold is placed on the payer's funds. The authorization is returned in `pending` status and transitions asynchronously to `succeeded` or `failed`. If `autoCapture` is enabled on the session, a capture is automatically created after a successful authorization. operationId: authorizeCoinbasePaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - oauth: [] parameters: - name: paymentSessionId in: path required: true description: >- The unique identifier of the payment session to authorize via Coinbase. schema: $ref: '#/components/schemas/PaymentSessionId' - name: cb-authz-id in: header required: true description: >- The `authorizationId` returned from a successful `POST https://login.coinbase.com/api/v1/authorization-challenges` step. Identifies the MFA challenge that gates this authorization. Must be a lowercase UUID v4. schema: type: string format: uuid minLength: 36 maxLength: 36 pattern: >- ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$ example: f47ac10b-58cc-4372-a567-0e02b2c3d479 - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CoinbaseAuthorizationRequest' example: metadata: customer_id: cust_12345 order_reference: order-67890 responses: '200': description: Successfully created Coinbase authorization. content: application/json: schema: $ref: '#/components/schemas/Authorization' example: authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: pending amount: '1.00' source: coinbaseUserId: coinbase_user_abc123 metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:01:00.000Z' updatedAt: '2025-06-15T12:01:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Payment session cannot be authorized in its current state. '403': description: >- The bearer token is valid but lacks the required `coinbase:stablecoins:payment-create` OAuth scope, or was minted from a CDP API key rather than an OAuth session. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_scope: summary: Bearer token is missing the required OAuth scope value: errorType: forbidden errorMessage: >- The bearer token does not have the required OAuth scope: coinbase:stablecoins:payment-create. wrong_auth_type: summary: Bearer token was minted from a CDP API key value: errorType: forbidden errorMessage: >- This endpoint requires a Coinbase OAuth bearer token; CDP API key tokens are not accepted. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/authorizations: get: summary: List payment session authorizations description: >- Returns a paginated list of authorizations for a payment session. Each authorization represents a hold on funds and includes its current status and amount. operationId: listPaymentSessionAuthorizations x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed authorizations. content: application/json: schema: allOf: - type: object required: - authorizations properties: authorizations: type: array description: The list of authorizations. items: $ref: '#/components/schemas/Authorization' - $ref: '#/components/schemas/ListResponse' example: authorizations: - authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc metadata: customer_id: cust_12345 order_id: order_67890 onchainTransactions: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:01:00.000Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/authorizations/{authorizationId}: get: summary: Get a payment session authorization description: >- Retrieves a single authorization by its ID, including its current status, amount, and any associated onchain transactions. operationId: getPaymentSessionAuthorization x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - name: authorizationId in: path required: true description: The unique identifier of the authorization. schema: $ref: '#/components/schemas/AuthorizationId' responses: '200': description: Successfully retrieved authorization. content: application/json: schema: $ref: '#/components/schemas/Authorization' example: authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc metadata: customer_id: cust_12345 order_id: order_67890 onchainTransactions: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:01:00.000Z' '404': description: Authorization not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Authorization with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/captures: post: summary: Capture a payment session description: >- Captures authorized funds. The session must have a positive `capturable` balance and the `captureExpiresAt` deadline must not have passed. This is an asynchronous operation. The capture is returned in `pending` status and transitions to `succeeded` or `failed`. Multiple partial captures are allowed. If `amount` is omitted, the full remaining capturable amount is captured. operationId: capturePaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCaptureRequest' example: amount: '1.00' finalCapture: true metadata: customer_id: cust_12345 order_id: order_67890 responses: '200': description: Successfully created capture. content: application/json: schema: $ref: '#/components/schemas/Capture' example: captureId: capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: pending amount: '1.00' finalCapture: true metadata: customer_id: cust_12345 order_id: order_67890 createdAt: '2025-06-15T12:20:00.000Z' updatedAt: '2025-06-15T12:20:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid capture parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' get: summary: List payment session captures description: >- Returns a paginated list of captures for a payment session. Each capture includes its status, amount, associated onchain transactions, and timestamps. Only captures accessible by the current API key are returned. operationId: listPaymentSessionCaptures x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed captures. content: application/json: schema: allOf: - type: object required: - captures properties: captures: type: array description: The list of captures. items: $ref: '#/components/schemas/Capture' - $ref: '#/components/schemas/ListResponse' example: captures: - captureId: capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' finalCapture: true metadata: customer_id: cust_12345 order_id: order_67890 onchainTransactions: - transactionHash: >- 0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678 network: base createdAt: '2025-06-15T12:20:00.000Z' updatedAt: '2025-06-15T12:21:00.000Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/captures/{captureId}: get: summary: Get a payment session capture description: >- Retrieves a single capture by its ID, including status, captured amount, associated onchain transactions, and timestamps. Only returns the capture if the API key has permission to access it. operationId: getPaymentSessionCapture x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - name: captureId in: path required: true description: The unique identifier of the capture. schema: $ref: '#/components/schemas/CaptureId' responses: '200': description: Successfully retrieved capture. content: application/json: schema: $ref: '#/components/schemas/Capture' example: captureId: capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' finalCapture: true metadata: customer_id: cust_12345 order_id: order_67890 onchainTransactions: - transactionHash: >- 0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678 network: base createdAt: '2025-06-15T12:20:00.000Z' updatedAt: '2025-06-15T12:21:00.000Z' '404': description: Capture not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Capture with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/voids: post: summary: Void a payment session description: >- Releases all remaining capturable funds back to the payer. The session must have a positive `capturable` balance. This is an asynchronous operation. The void is returned in `pending` status and transitions to `succeeded` or `failed`. After voiding, no further captures can be made. Unlike **Cancel**, which works before authorization, void works after authorization. operationId: voidPaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateVoidRequest' example: metadata: customer_id: cust_12345 reason: customer_request responses: '200': description: Successfully created void. content: application/json: schema: $ref: '#/components/schemas/Void' example: voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: pending amount: '1.00' metadata: customer_id: cust_12345 reason: customer_request createdAt: '2025-06-15T12:30:00.000Z' updatedAt: '2025-06-15T12:30:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid void parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' get: summary: List payment session voids description: >- Returns a paginated list of voids for a payment session. Each void includes its status, amount, associated onchain transactions, and timestamps. Only voids accessible by the current API key are returned. operationId: listPaymentSessionVoids x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed voids. content: application/json: schema: allOf: - type: object required: - voids properties: voids: type: array description: The list of voids. items: $ref: '#/components/schemas/Void' - $ref: '#/components/schemas/ListResponse' example: voids: - voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' metadata: customer_id: cust_12345 reason: customer_request onchainTransactions: - transactionHash: >- 0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12 network: base createdAt: '2025-06-15T12:30:00.000Z' updatedAt: '2025-06-15T12:31:00.000Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/voids/{voidId}: get: summary: Get a payment session void description: >- Retrieves a single void by its ID, including status, voided amount, associated onchain transactions, and timestamps. Only returns the void if the API key has permission to access it. operationId: getPaymentSessionVoid x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - name: voidId in: path required: true description: The unique identifier of the void. schema: $ref: '#/components/schemas/VoidId' responses: '200': description: Successfully retrieved void. content: application/json: schema: $ref: '#/components/schemas/Void' example: voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' metadata: customer_id: cust_12345 reason: customer_request onchainTransactions: - transactionHash: >- 0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12 network: base createdAt: '2025-06-15T12:30:00.000Z' updatedAt: '2025-06-15T12:31:00.000Z' '404': description: Void not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Void with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/refunds: post: summary: Refund a payment session description: >- Returns captured funds to the payer. The session must have a positive `refundable` balance and the `refundExpiresAt` deadline must not have passed. This is an asynchronous operation. The refund is returned in `pending` status and transitions to `succeeded` or `failed`. If `amount` is omitted, the full remaining refundable amount is refunded. Multiple partial refunds are supported. operationId: refundPaymentSession x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRefundRequest' example: source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc amount: '0.50' reason: Customer returned the item. metadata: customer_id: cust_12345 order_id: order_67890 responses: '200': description: Successfully created refund. content: application/json: schema: $ref: '#/components/schemas/Refund' example: refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc status: pending amount: '0.50' reason: Customer returned the item. metadata: customer_id: cust_12345 order_id: order_67890 createdAt: '2025-06-15T12:40:00.000Z' updatedAt: '2025-06-15T12:40:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid refund parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' get: summary: List payment session refunds description: >- Returns a paginated list of refunds for a payment session. Each refund includes its status, amount, reason, associated onchain transactions, and timestamps. Only refunds accessible by the current API key are returned. operationId: listPaymentSessionRefunds x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed refunds. content: application/json: schema: allOf: - type: object required: - refunds properties: refunds: type: array description: The list of refunds. items: $ref: '#/components/schemas/Refund' - $ref: '#/components/schemas/ListResponse' example: refunds: - refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc status: succeeded amount: '0.50' metadata: customer_id: cust_12345 order_id: order_67890 reason: Customer returned the item. onchainTransactions: - transactionHash: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 network: base createdAt: '2025-06-15T12:40:00.000Z' updatedAt: '2025-06-15T12:41:00.000Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '404': description: Payment session not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment session with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/payment-sessions/{paymentSessionId}/refunds/{refundId}: get: summary: Get a payment session refund description: >- Retrieves a single refund by its ID, including status, refunded amount, reason, associated onchain transactions, and timestamps. Only returns the refund if the API key has permission to access it. operationId: getPaymentSessionRefund x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: paymentSessionId in: path required: true description: The unique identifier of the payment session. schema: $ref: '#/components/schemas/PaymentSessionId' - name: refundId in: path required: true description: The unique identifier of the refund. schema: $ref: '#/components/schemas/RefundId' responses: '200': description: Successfully retrieved refund. content: application/json: schema: $ref: '#/components/schemas/Refund' example: refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc status: succeeded amount: '0.50' metadata: customer_id: cust_12345 order_id: order_67890 reason: Customer returned the item. onchainTransactions: - transactionHash: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 network: base createdAt: '2025-06-15T12:40:00.000Z' updatedAt: '2025-06-15T12:41:00.000Z' '404': description: Refund not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Refund with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/disbursements: post: summary: Create a disbursement description: >- Creates a merchant-initiated payment of funds from a CDP account owned by the merchant to a Coinbase user account or onchain address. Used for standalone refunds, goodwill disbursements, rebates, and other merchant-driven payouts that are not tied to a specific payment session. This is an asynchronous operation. The disbursement is returned in `pending` status and transitions to `succeeded` (with associated `onchainTransactions`) or `failed` (with `error`). operationId: createDisbursement x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateDisbursementRequest' examples: coinbase_target: summary: Disbursement to a Coinbase user value: source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: coinbaseUserId: coinbase_user_abc123 amount: '25.00' asset: usdc reason: Goodwill disbursement for delayed shipment. externalReferenceId: disbursement-2026-04-1234 metadata: customer_id: cust_12345 order_id: order_67890 wallet_target: summary: Disbursement to an onchain address value: source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base amount: '10.00' asset: usdc reason: 'Rebate for overcharge on order #5678.' externalReferenceId: rebate-2026-04-5678 metadata: customer_id: cust_67890 order_id: order_55555 responses: '200': description: Successfully created disbursement. content: application/json: schema: $ref: '#/components/schemas/Disbursement' example: disbursementId: disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: coinbaseUserId: coinbase_user_abc123 amount: '25.00' asset: usdc status: pending reason: Goodwill disbursement for delayed shipment. externalReferenceId: disbursement-2026-04-1234 metadata: customer_id: cust_12345 order_id: order_67890 createdAt: '2026-04-17T17:00:00.000Z' updatedAt: '2026-04-17T17:00:00.000Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid disbursement parameters. '422': $ref: '#/components/responses/IdempotencyError' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' get: summary: List disbursements description: >- Returns a paginated list of disbursements created by the merchant. Each disbursement includes its source, target, status, amount, and timestamps. Only disbursements accessible by the current API key are returned. operationId: listDisbursements x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' - name: status in: query required: false description: Filter disbursements by status. schema: $ref: '#/components/schemas/PaymentActionStatus' example: pending - name: sourceAccountId in: query required: false description: Filter disbursements by the source CDP account ID. schema: type: string example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 - name: externalReferenceId in: query required: false description: Filter disbursements by the client-supplied external reference ID. schema: type: string example: disbursement-2026-04-1234 responses: '200': description: Successfully listed disbursements. content: application/json: schema: allOf: - type: object required: - disbursements properties: disbursements: type: array description: The list of disbursements. items: $ref: '#/components/schemas/Disbursement' - $ref: '#/components/schemas/ListResponse' example: disbursements: - disbursementId: disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: coinbaseUserId: coinbase_user_abc123 amount: '25.00' asset: usdc status: succeeded reason: Goodwill disbursement for delayed shipment. externalReferenceId: disbursement-2026-04-1234 metadata: customer_id: cust_12345 order_id: order_67890 onchainTransactions: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: '2026-04-17T17:00:00.000Z' updatedAt: '2026-04-17T17:05:00.000Z' nextPageToken: >- eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid query parameters. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/disbursements/{disbursementId}: get: summary: Get a disbursement description: >- Retrieves a single disbursement by its ID, including source, target, status, amount, associated onchain transactions, error details (if failed), and timestamps. Only returns the disbursement if the API key has permission to access it. operationId: getDisbursement x-audience: development tags: - Payment Acceptance (Under Development) security: - apiKeyAuth: [] parameters: - name: disbursementId in: path required: true description: The unique identifier of the disbursement. schema: $ref: '#/components/schemas/DisbursementId' responses: '200': description: Successfully retrieved disbursement. content: application/json: schema: $ref: '#/components/schemas/Disbursement' example: disbursementId: disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: coinbaseUserId: coinbase_user_abc123 amount: '25.00' asset: usdc status: succeeded reason: Goodwill disbursement for delayed shipment. externalReferenceId: disbursement-2026-04-1234 metadata: customer_id: cust_12345 order_id: order_67890 onchainTransactions: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: '2026-04-17T17:00:00.000Z' updatedAt: '2026-04-17T17:05:00.000Z' '404': description: Disbursement not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Disbursement with the given ID does not exist. '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGatewayError' '503': $ref: '#/components/responses/ServiceUnavailableError' /v2/data/webhooks/subscriptions: get: operationId: listWebhookSubscriptions summary: List webhook subscriptions x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any description: > Retrieve a paginated list of webhook subscriptions for the authenticated project. Returns subscriptions for all CDP product events (onchain, onramp/offramp, wallet, etc.) in descending order by creation time. ### Use Cases - Monitor all active webhook subscriptions across CDP products - Audit webhook configurations - Manage subscription lifecycle tags: - Webhooks security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: pageSize description: The number of subscriptions to return per page. in: query required: false schema: type: integer default: 20 minimum: 1 maximum: 100 example: 10 - name: pageToken description: The token for the next page of subscriptions, if any. in: query required: false schema: type: string example: eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== responses: '200': description: Webhook subscriptions retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionListResponse' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_page_size: value: errorType: invalid_request errorMessage: Page size must be between 1 and 100. invalid_page_token: value: errorType: invalid_request errorMessage: Invalid page token format. '401': $ref: '#/components/responses/UnauthorizedError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Too many requests. Please try again later. '500': $ref: '#/components/responses/InternalServerError' post: operationId: createWebhookSubscription summary: Create webhook subscription x-audience: public x-required-permissions: permissions: - accounts:write@entity enforcement: any description: > Subscribe to real-time events across CDP products. ### Filtering Onchain events can utilize multi-label filtering to only receive events that match all the specified labels. Allows labels are: - `network` (required) — Blockchain network - `contract_address` — Smart contract address - `event_name` — Event name (e.g., "Transfer", "Burn") - `event_signature` — Event signature (e.g., "Transfer(address,address,uint256)") - `transaction_from` — Transaction sender address - `transaction_to` — Transaction recipient address - `params.*` — Any event parameter from the log event (e.g., `params.from`, `params.to`, `params.sender`, `params.tokenId`) For webhook types that aren't `onchain.*`, labels are ignored. ### Webhook Signature Verification All webhooks include an HMAC-SHA256 signed header for security. The signature is signed with the secret that is returned in the `secret` field when creating a subscription. Do not lose the secret, as you will not be able to recreate it. If you lose the secret, you will need to create a new subscription. See the [verification guide](https://docs.cdp.coinbase.com/onramp-&-offramp/webhooks#webhook-signature-verification) for implementation details. tags: - Webhooks security: - apiKeyAuth: [] - sessionAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionRequest' examples: onchain_liquidity_pool: summary: 'Onchain: Monitor liquidity pool burns' value: description: Liquidity pool burn events. eventTypes: - onchain.activity.detected labels: network: base-mainnet contract_address: '0xcd1f9777571493aeacb7eae45cd30a226d3e612d' event_name: Burn target: url: https://api.example.com/webhooks isEnabled: true wallet_outgoing_transactions: summary: 'Wallet: Monitor outgoing transactions' value: description: Outgoing transactions. eventTypes: - wallet.activity.detected labels: network: base-mainnet params.from: '0xB7f5BF799fB265657c628ef4a13f90f83a3a616A' target: url: https://api.example.com/webhooks isEnabled: true responses: '201': description: Webhook subscription created successfully. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionResponse' '400': description: Invalid subscription configuration. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_url: value: errorType: invalid_request errorMessage: Target URL must be a valid HTTPS endpoint. invalid_event_types: value: errorType: invalid_request errorMessage: >- Event types must be non-empty and contain valid event type names. '401': $ref: '#/components/responses/UnauthorizedError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Too many requests. Please try again later. '500': $ref: '#/components/responses/InternalServerError' /v2/data/webhooks/subscriptions/{subscriptionId}: get: operationId: getWebhookSubscription summary: Get webhook subscription x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any description: > Retrieve detailed information about a specific webhook subscription including configuration, status, creation timestamp, and webhook signature secret. ### Response Includes - Subscription configuration and filters - Target URL and custom headers - Webhook signature secret for verification - Creation timestamp and status tags: - Webhooks security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: subscriptionId in: path required: true description: Unique identifier for the webhook subscription. schema: type: string format: uuid pattern: ^[a-f0-9\-]{36}$ example: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: Webhook subscription details retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Webhook subscription not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: subscription_not_found: value: errorType: not_found errorMessage: Webhook subscription not found. '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Too many requests. Please try again later. '500': $ref: '#/components/responses/InternalServerError' put: operationId: updateWebhookSubscription summary: Update webhook subscription x-audience: public x-required-permissions: permissions: - accounts:write@entity enforcement: any description: > Update an existing webhook subscription's configuration including event types, target URL, filtering criteria, and enabled status. All required fields must be provided, even if they are not being changed. ### Common Updates - Change target URL or headers - Add/remove event type filters - Update multi-label filtering criteria - Enable/disable subscription tags: - Webhooks security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: subscriptionId in: path required: true description: Unique identifier for the webhook subscription. schema: type: string format: uuid pattern: ^[a-f0-9\-]{36}$ example: 123e4567-e89b-12d3-a456-426614174000 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionUpdateRequest' responses: '200': description: Webhook subscription updated successfully. content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionResponse' '400': description: Invalid subscription update configuration. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_url: value: errorType: invalid_request errorMessage: Target URL must be a valid HTTPS endpoint. invalid_event_types: value: errorType: invalid_request errorMessage: >- Event types must be non-empty and contain valid event type names. '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Webhook subscription not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: subscription_not_found: value: errorType: not_found errorMessage: Webhook subscription not found. '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Too many requests. Please try again later. '500': $ref: '#/components/responses/InternalServerError' delete: operationId: deleteWebhookSubscription summary: Delete webhook subscription x-audience: public x-required-permissions: permissions: - accounts:write@entity enforcement: any description: | Permanently delete a webhook subscription and stop all event deliveries. This action cannot be undone. ### Important Notes - All webhook deliveries will cease immediately - Subscription cannot be recovered after deletion - Consider disabling instead of deleting for temporary pauses tags: - Webhooks security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: subscriptionId in: path required: true description: Unique identifier for the webhook subscription. schema: type: string format: uuid pattern: ^[a-f0-9\-]{36}$ example: 123e4567-e89b-12d3-a456-426614174000 responses: '204': description: Webhook subscription deleted successfully. '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Webhook subscription not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: subscription_not_found: value: errorType: not_found errorMessage: Webhook subscription not found. '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Too many requests. Please try again later. '500': $ref: '#/components/responses/InternalServerError' /v2/data/webhooks/subscriptions/{subscriptionId}/events: get: operationId: listWebhookSubscriptionEvents summary: List webhook subscription events x-audience: public x-required-permissions: permissions: - accounts:read@entity enforcement: any description: > Retrieve webhook event delivery attempts for a specific subscription. Returns event deliveries in descending order by creation time (newest first), including delivery status, retry count, and response details. ### Use Cases - Debug webhook delivery failures and inspect response codes - Monitor delivery status and retry counts - Audit event delivery history for a subscription - Verify that expected events were sent to webhook URLs ### Filtering Use optional query parameters to narrow results: - `eventId` — find a specific event by ID - `minCreatedAt` / `maxCreatedAt` — filter by time range - `eventTypeNames` — filter by event type (comma-separated) **Note:** Results are limited to the 50 most recent events (newest first). No pagination is supported. tags: - Webhooks security: - apiKeyAuth: [] - sessionAuth: [] parameters: - name: subscriptionId in: path required: true description: Unique identifier for the webhook subscription. schema: type: string format: uuid pattern: ^[a-f0-9\-]{36}$ example: 123e4567-e89b-12d3-a456-426614174000 - name: eventId in: query required: false description: Filter by a specific event ID. schema: type: string format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 - name: minCreatedAt in: query required: false description: Filter events created at or after this timestamp (RFC 3339 format). schema: type: string format: date-time example: '2025-01-15T00:00:00Z' - name: maxCreatedAt in: query required: false description: Filter events created at or before this timestamp (RFC 3339 format). schema: type: string format: date-time example: '2025-01-16T00:00:00Z' - name: eventTypeNames in: query required: false description: Filter by event type names (comma-separated). schema: type: string example: onchain.activity.detected responses: '200': description: Webhook events retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/WebhookEventListResponse' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_min_created_at: value: errorType: invalid_request errorMessage: minCreatedAt must be a valid RFC 3339 timestamp. invalid_max_created_at: value: errorType: invalid_request errorMessage: maxCreatedAt must be a valid RFC 3339 timestamp. unknown_event_type_names: value: errorType: invalid_request errorMessage: 'Unknown event type names: invalid.event.type.' '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Webhook subscription not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: subscription_not_found: value: errorType: not_found errorMessage: Webhook subscription not found. '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: value: errorType: rate_limit_exceeded errorMessage: Too many requests. Please try again later. '500': $ref: '#/components/responses/InternalServerError' /v2/payment-methods: get: x-audience: public summary: List payment methods description: >- List payment methods linked to your entity. Payment methods represent external financial instruments that can be used as a target for transfers. The list will not include disabled or deleted payment methods. **Currently Supported Types:** - `fedwire`: Domestic USD wire transfers - `swift`: International wire transfers - `sepa`: SEPA EUR transfers **Note:** Payment methods are created and verified through your linked CDP entity. Currently, fetching payment methods is only supported for Prime investment vehicles linked to CDP. operationId: listPaymentMethods tags: - Payment Methods security: - apiKeyAuth: [] - sessionAuth: [] x-required-permissions: permissions: - accounts:read@entity enforcement: any parameters: - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Successfully listed payment methods. content: application/json: schema: allOf: - type: object required: - paymentMethods properties: paymentMethods: type: array description: The list of payment methods. items: $ref: '#/components/schemas/payment-methods_PaymentMethod' - $ref: '#/components/schemas/ListResponse' example: paymentMethods: - paymentMethodId: paymentMethod_8e03978e-40d5-43e8-bc93-6894a57f9324 paymentRail: fedwire active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' fedwire: asset: usd bankName: ALLY BANK accountLast4: '1234' routingNumber: '124003116' - paymentMethodId: paymentMethod_def45678-1234-5678-9abc-def012345678 paymentRail: swift active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' swift: asset: eur bankName: Deutsche Bank accountLast4: '5678' ibanLast4: '5678' bic: DEUTDEFF - paymentMethodId: paymentMethod_abc12345-6789-0abc-def0-123456789abc paymentRail: sepa active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' sepa: asset: eur bankName: ING Bank ibanLast4: '4300' bic: INGBNL2A nextPageToken: eyJsYXN0X2lkIjogImFiYzEyMyJ9 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid page token format. '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/InternalServerError' /v2/payment-methods/{paymentMethodId}: get: x-audience: public summary: Get payment method description: >- Get details of a specific payment method by its ID. Returns 404 if the payment method is not found or not owned by the requesting entity. operationId: getPaymentMethod security: - apiKeyAuth: [] - sessionAuth: [] x-required-permissions: permissions: - accounts:read@entity enforcement: any tags: - Payment Methods parameters: - name: paymentMethodId in: path required: true description: The unique identifier of the payment method. schema: $ref: '#/components/schemas/PaymentMethodId' example: paymentMethod_8e03978e-40d5-43e8-bc93-6894a57f9324 responses: '200': description: Successfully retrieved payment method. content: application/json: schema: $ref: '#/components/schemas/payment-methods_PaymentMethod' examples: fedwire: summary: Fedwire payment method value: paymentMethodId: paymentMethod_8e03978e-40d5-43e8-bc93-6894a57f9324 paymentRail: fedwire active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' fedwire: asset: usd bankName: ALLY BANK accountLast4: '1234' routingNumber: '124003116' swift: summary: SWIFT payment method value: paymentMethodId: paymentMethod_def45678-1234-5678-9abc-def012345678 paymentRail: swift active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' swift: asset: eur bankName: Deutsche Bank accountLast4: '5678' ibanLast4: '5678' bic: DEUTDEFF sepa: summary: SEPA payment method value: paymentMethodId: paymentMethod_abc12345-6789-0abc-def0-123456789abc paymentRail: sepa active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' sepa: asset: eur bankName: ING Bank ibanLast4: '4300' bic: INGBNL2A '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: errorType: invalid_request errorMessage: Invalid payment method ID format. '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Payment method not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: errorType: not_found errorMessage: Payment method not found. '500': $ref: '#/components/responses/InternalServerError' webhooks: {} components: securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: JWT description: >- A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the [Generate Bearer Token](https://docs.cdp.coinbase.com/api-reference/v2/authentication#2-generate-bearer-token) section of our Authentication docs for information on how to generate your Bearer Token. endUserAuth: x-audience: public type: http scheme: bearer bearerFormat: JWT description: >- A JWT signed using the developer's own JWT private key (in the case of JWT authentication), or an end user JWT signed by CDP, encoded in base64. This is used for End User Account APIs. unauthenticated: x-audience: public type: http scheme: none description: >- This security scheme is used for APIs that do not require authentication, such as End User Auth flows used to initiate authentication or public, read-only endpoints. oauth: x-audience: development type: http scheme: bearer description: >- A Coinbase OAuth Bearer token provided by the end user (payer). EntryGateway terminates the OAuth token and mints a scoped CAT (Coinbase Auth Token) JWT for downstream services. webhookSignature: x-audience: public type: apiKey in: header name: X-Hook0-Signature description: >- HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Webhook receivers should always verify this header before processing the event. The header value is hex-encoded and prefixed by the algorithm and timestamp, e.g. `t=1700000000,v1=abc123...` (refer to the Webhook Security docs for the exact verification algorithm). This scheme applies to webhook delivery (outbound POSTs from CDP to your endpoint), not to inbound CDP API requests. parameters: PageSize: name: pageSize description: The number of resources to return per page. in: query required: false schema: type: integer default: 20 example: 10 PageToken: name: pageToken description: The token for the next page of resources, if any. in: query required: false schema: type: string example: eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== IdempotencyKey: name: X-Idempotency-Key in: header required: false description: > An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our [Idempotency docs](https://docs.cdp.coinbase.com/api-reference/v2/idempotency) for more information on using idempotency keys. schema: type: string maxLength: 128 minLength: 1 example: 8e03978e-40d5-43e8-bc93-6894a57f9324 schemas: AccountType: type: string description: The type of the Account. enum: - prime - business - cdp example: prime AccountId: type: string pattern: ^account_[a-f0-9\-]{36}$ description: >- The ID of the Account, which is a UUID prefixed by the string `account_`. example: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 Owner: type: string description: >- The Owner ID of the Account. Owner IDs are UUIDs prefixed with the Owner Type as follows: * **Entity**: `entity_` - If the Owner is your Entity, e.g. `entity_af2937b0-9846-4fe7-bfe9-ccc22d935114`. Support for Customer-owned accounts (`customer_` prefix) is in development. pattern: >- ^(entity|customer)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 AccountName: type: string pattern: ^[a-zA-Z0-9 -]{1,64}$ maxLength: 64 description: >- An optional name for the account. Must be 1-64 characters and can only contain alphanumeric characters, hyphens, and spaces. example: My Business Account Account: type: object properties: accountId: $ref: '#/components/schemas/AccountId' type: $ref: '#/components/schemas/AccountType' owner: $ref: '#/components/schemas/Owner' name: $ref: '#/components/schemas/AccountName' createdAt: type: string format: date-time description: The timestamp when the account was created. example: '2023-10-08T14:30:00Z' updatedAt: type: string format: date-time description: The timestamp when the account was last updated. example: '2023-10-08T14:30:00Z' required: - accountId - type - owner - createdAt - updatedAt ListResponse: type: object properties: nextPageToken: type: string description: The token for the next page of items, if any. example: eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ== ErrorType: description: >- The code that indicates the type of error that occurred. These error codes can be used to determine how to handle the error. type: string example: invalid_request enum: - already_exists - authorization_expired - bad_gateway - capture_expired - client_closed_request - customer_not_authorized - endpoint_unavailable - faucet_limit_exceeded - forbidden - idempotency_error - internal_server_error - invalid_request - invalid_sql_query - invalid_signature - malformed_transaction - not_found - payment_method_required - payment_required - settlement_failed - rate_limit_exceeded - request_canceled - service_unavailable - timed_out - unauthorized - unsupported_tos_language - policy_violation - policy_in_use - account_limit_exceeded - network_not_tradable - guest_permission_denied - guest_region_forbidden - guest_transaction_limit - guest_transaction_count - phone_number_verification_expired - document_verification_failed - recipient_allowlist_violation - recipient_allowlist_pending - refund_expired - travel_rules_recipient_violation - source_account_invalid - target_account_invalid - source_account_not_found - target_account_not_found - source_asset_not_supported - target_asset_not_supported - target_email_invalid - target_onchain_address_invalid - transfer_amount_invalid - transfer_asset_not_supported - transfer_quote_expired - insufficient_balance - metadata_too_many_entries - metadata_key_too_long - metadata_value_too_long - travel_rules_field_missing - asset_mismatch - mfa_already_enrolled - mfa_invalid_code - mfa_flow_expired - mfa_required - mfa_not_enrolled - order_quote_expired - order_already_filled - order_already_canceled - account_not_ready - insufficient_liquidity - insufficient_allowance - transaction_simulation_failed - delegation_not_found - delegation_expired - delegation_revoked - delegation_not_authorized - delegation_not_enabled - network_mismatch - already_enabled x-error-instructions: already_exists: >- This error occurs when trying to create a resource that already exists. **Steps to resolve:** 1. Check if the resource exists before creation 2. Use GET endpoints to verify resource state 3. Use unique identifiers/names for resources authorization_expired: >- Returned when an authorization attempt is made after the payment session's authorization deadline has passed. Create a new payment session with a later authorization deadline. bad_gateway: >- This error occurs when the CDP API is unable to connect to the backend service. **Steps to resolve:** 1. Retry your request after a short delay 2. If persistent, contact CDP support with: - The timestamp of the error - Request details 3. Consider implementing retry logic with an exponential backoff **Note:** These errors are automatically logged and monitored by CDP. capture_expired: >- Returned when a capture attempt is made after the payment session's capture deadline has passed. The payment session can no longer be captured. client_closed_request: >- This error occurs when the client closes the connection before the server can send a response. **Common causes:** - The client timed out waiting for the server response - The client application was terminated during a pending request - Network interruption caused the client connection to drop **Steps to resolve:** 1. Increase client-side timeout settings if applicable 2. Implement retry logic with exponential backoff for long-running queries 3. Consider optimizing the request to reduce server processing time endpoint_unavailable: >- This error occurs when a specific endpoint has been temporarily disabled by an operator (e.g. a kill switch). The CDP API as a whole is still healthy; only this endpoint is unavailable. Distinct from `service_unavailable`, which indicates the API itself is down. Re-enabling is a manual operator action, so the endpoint may remain unavailable for an extended period. **Steps to resolve:** 1. Check the [CDP status page](https://cdpstatus.coinbase.com/) for an active incident. 2. If persistent, contact CDP support with: - The timestamp of the error - Request details faucet_limit_exceeded: >- This error occurs when you've exceeded the faucet request limits. **Steps to resolve:** 1. Wait for the time window to reset 2. Use funds more efficiently in your testing For more information on faucet limits, please visit the [EVM Faucet endpoint](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/faucets/request-funds-on-evm-test-networks) or the [Solana Faucet endpoint](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/faucets/request-funds-on-solana-devnet). customer_not_authorized: >- This error occurs when the customer is not currently authorized for one or more capabilities required to perform the requested action. This can happen at any point in the customer's lifecycle and may or may not be resolvable by the developer. The response includes an `unauthorizedCapabilities` field listing the capability code(s) that were not authorized on this request. **Steps to resolve:** 1. Fetch the customer with `GET /v2/customers/{customerId}` and inspect the `requirements` field. If `requirements.due` is non-empty, submit the listed fields via `POST /v2/customers/{customerId}` and retry. 2. If `requirements.due` is empty, no further action is available — the customer is not currently eligible for this action. forbidden: >- This error occurs when you don't have permission to access the resource. **Steps to resolve:** 1. Verify your permissions to access the resource 2. Ensure that you are the owner of the requested resource idempotency_error: >- This error occurs when an idempotency key is reused with different parameters. **Steps to resolve:** 1. Generate a new UUID v4 for each unique request 2. Only reuse idempotency keys for exact request duplicates 3. Track used keys within your application **Example idempotency key implementation:** ```typescript lines wrap import { v4 as uuidv4 } from 'uuid'; function createIdempotencyKey() { return uuidv4(); } ``` internal_server_error: >- This indicates an unexpected error that occurred on the CDP servers. **Important**: If you encounter this error, please note that your operation's status should be treated as unknown by your application, as it could have been a success within the CDP back-end. **Steps to resolve:** 1. Retry your request after a short delay 2. If persistent, contact CDP support with: - Your correlation ID - Timestamp of the error - Request details 3. Consider implementing retry logic with an exponential backoff **Note:** These errors are automatically logged and monitored by CDP. invalid_request: >- This error occurs when the request is malformed or contains invalid data, including issues with the request body, query parameters, path parameters, or headers. **Steps to resolve:** 1. Check all required fields and parameters are present 2. Ensure request body (if applicable) follows the correct schema 3. Verify all parameter formats match the API specification: - Query parameters - Path parameters - Request headers 4. Validate any addresses, IDs, or other formatted strings meet requirements **Common validation issues:** - Missing required parameters - Invalid parameter types or formats - Malformed JSON in request body - Invalid enum values #### Transfer-specific validation errors The following transfer validation scenarios return `errorType: "invalid_request"`. Use the `errorMessage` field to identify the specific case. | Scenario | Example `errorMessage` | |----------|----------------------| | Source account ID is malformed | `"source is invalid."` | | Target account ID is malformed | `"target is invalid."` | | Source account does not exist | `"source not found."` | | Target account does not exist | `"target not found."` | | Asset not supported at source | `"source is not supported."` | | Asset not supported at target | `"target is not supported."` | | Target email address is malformed | `"target has an invalid email format."` | | Target onchain address is invalid for network | `"The recipient address is invalid for the selected network."` | | Asset not supported for this transfer route | `"Transfer asset pair is not supported."` | | Insufficient balance | `"Insufficient funds to complete this transfer."` | | Asset mismatch between request fields | `"Currency mismatch in request."` | | Metadata has too many keys | `"Metadata has too many keys. Up to 10 key/value pairs are permitted."` | | Metadata key exceeds length limit | `"Metadata key is too long. Each key must be less than or equal to 40 characters."` | | Metadata value exceeds length limit | `"Metadata value is too long. Each value must be less than or equal to 500 characters."` | | Travel rule fields missing | `"Travel rule information is incomplete. Missing fields: ..."` | | Recipient address not in account allowlist | `"Your coinbase account allowlist does not include this address. Please update your allowlist at https://www.coinbase.com/settings/allowlist"` | invalid_sql_query: |- This error occurs when the SQL query is invalid or not allowed. **Common causes:** - Using non-SELECT SQL statements (INSERT, UPDATE, DELETE, etc.) - Invalid table or column names - Syntax errors in SQL query - Query exceeds character limit - Too many JOIN operations invalid_signature: >- This error occurs when the signature provided for the given user operation is invalid. **Steps to resolve:** 1. Verify the signature was generated by the correct owner account 2. Ensure the signature corresponds to the exact user operation hash 3. Check that the signature format matches the expected format 4. Confirm you're using the correct network for the Smart Account **Common causes:** - Using wrong owner account to sign - Signing modified/incorrect user operation data - Malformed signature encoding - Network mismatch between signature and broadcast malformed_transaction: >- This error occurs when the transaction data provided is not properly formatted or is invalid. **Steps to resolve:** 1. Verify transaction encoding: - **EVM networks**: Check RLP encoding is correct - **Solana**: Validate base64 encoding 2. Ensure all required transaction fields are present 3. Validate transaction parameters are within acceptable ranges 4. Check that the transaction type is supported on the target network (see our [Supported Networks](https://docs.cdp.coinbase.com/get-started/supported-networks) page for more details) **Common causes:** - Invalid hex encoding for EVM transactions - Missing required transaction fields - Incorrect parameter formats - Unsupported transaction types - Network-specific transaction format mismatches not_found: >- This error occurs when the resource specified in your request doesn't exist or you don't have access to it. **Steps to resolve:** 1. Verify the resource ID/address/account exists 2. Check your permissions to access the resource 3. Ensure you're using the correct network/environment 4. Confirm the resource hasn't been deleted **Common causes:** - Mistyped addresses - Accessing resources from the wrong CDP project - Resource was deleted or hasn't been created yet payment_method_required: >- This error occurs when a payment method is required to complete the requested operation but none is configured or available. **Steps to resolve:** 1. Add a valid payment method to your account using the [CDP Portal](https://portal.cdp.coinbase.com) 2. Ensure your payment method is valid and not expired **Common causes:** - No payment method configured on the account - Payment method is expired payment_required: >- This error occurs when an x402 payment is required to access the requested resource. **Steps to resolve:** 1. Include a valid x402 payment header in your request 2. Ensure the payment meets the resource's pricing requirements settlement_failed: >- This error occurs when an x402 payment was verified but settlement on-chain failed. **Steps to resolve:** 1. Retry the request with a new payment 2. Ensure the payment asset has sufficient balance for settlement rate_limit_exceeded: |- This error occurs when you've exceeded the API rate limits. **Steps to resolve:** 1. Implement exponential backoff 2. Cache responses where possible 3. Wait for rate limit window to reset **Best practices:** ```typescript lines wrap async function withRetry(fn: () => Promise) { let delay = 1000; while (true) { try { return await fn(); } catch (e) { if (e.errorType === "rate_limit_exceeded") { await sleep(delay); delay *= 2; continue; } throw e; } } } ``` request_canceled: >- This error occurs when the client cancels an in-progress request before it completes. **Steps to resolve:** 1. Check client-side timeout configurations 2. Review request cancellation logic in your code 3. Consider increasing timeout thresholds for long-running operations 4. Implement request tracking to identify premature cancellations **Best practices:** ```typescript lines wrap async function withTimeout(promise: Promise, timeoutMs: number): Promise { const timeout = new Promise((_, reject) => { setTimeout(() => { reject(new Error("Operation timed out")); }, timeoutMs); }); try { return await Promise.race([promise, timeout]); } catch (error) { // Handle timeout or cancellation throw error; } } ``` service_unavailable: >- This error occurs when the CDP API is temporarily unable to handle requests due to maintenance or high load. **Steps to resolve:** 1. Retry your request after a short delay 2. If persistent, contact CDP support with: - The timestamp of the error - Request details 3. Consider implementing retry logic with an exponential backoff **Note:** These errors are automatically logged and monitored by CDP. timed_out: >- This error occurs when a request exceeds the maximum allowed processing time. **Steps to resolve:** 1. Break down large requests into smaller chunks (if applicable) 2. Implement retry logic with exponential backoff 3. Use streaming endpoints for large data sets **Example retry implementation:** ```typescript lines wrap async function withRetryAndTimeout( operation: () => Promise, maxRetries = 3, timeout = 30000, ): Promise { let attempts = 0; while (attempts < maxRetries) { try { return await Promise.race([ operation(), new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), timeout) ), ]); } catch (error) { attempts++; if (attempts === maxRetries) throw error; // Exponential backoff await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempts) * 1000) ); } } throw new Error("Max retries exceeded"); } ``` unauthorized: |- This error occurs when authentication fails. **Steps to resolve:** 1. Verify your CDP API credentials: - Check that your API key is valid - Check that your Wallet Secret is properly configured 2. Validate JWT token: - Not expired - Properly signed - Contains required claims 3. Check request headers: - Authorization header present - X-Wallet-Auth header included when required **Security note:** Never share your Wallet Secret or API keys. unsupported_tos_language: >- A submitted Terms of Service acceptance used a `language` that is not published for the referenced `versionId`. **Steps to resolve:** 1. Read `Customer.requirements.tos.tosVersions[]` and find the entry whose `versionId` matches your acceptance. 2. Choose a `language` from that entry's `languages` list (BCP 47 tags). 3. Retry with `tosAcceptances[].language` set to a supported tag. policy_in_use: >- This error occurs when trying to delete a Policy that is currently in use by at least one project or account. **Steps to resolve:** 1. Update project or accounts to remove references to the Policy in question. 2. Retry your delete request. network_not_tradable: >- This error occurs when the selected asset cannot be purchased on the selected network in the user's location. **Steps to resolve:** 1. Verify the asset is tradable on the selected network 2. Check the user's location to ensure it is allowed to purchase the asset on the selected network **Common causes:** - Users in NY are not allowed to purchase USDC on any network other than Ethereum guest_permission_denied: >- This error occurs when the user is not allowed to complete onramp transactions as a guest. **Steps to resolve:** 1. Redirect the user to create a Coinbase account to buy and send crypto. guest_region_forbidden: >- This error occurs when guest onramp transactions are not allowed in the user's region. **Steps to resolve:** 1. Redirect the user to create a Coinbase account to buy and send crypto. guest_transaction_limit: >- This error occurs when the user has reached the weekly guest onramp transaction limit. **Steps to resolve:** 1. Inform the user they have reached their weekly limit and will have to wait until next week. guest_transaction_count: >- This error occurs when the user has reached the lifetime guest onramp transaction count limit. **Steps to resolve:** 1. Redirect the user to create a Coinbase account to buy and send crypto. phone_number_verification_expired: >- This error occurs when the user's phone number verification has expired. Use of guest Onramp requires the user's phone number to be verified every 60 days. **Steps to resolve:** 1. Re-verify the user's phone number via OTP. 2. Retry the request with the phoneNumberVerifiedAt field set to new verification timestamp. document_verification_failed: >- This error occurs when the user has not verified their identity for their coinbase.com account. **Steps to resolve:** 1. Verify your coinbase account identity with valid documents at https://www.coinbase.com/settings/account-levels. recipient_allowlist_violation: >- This error occurs when the user is not allowed to receive funds at this address, according to their coinbase account allowlist. **Steps to resolve:** 1. Either disable the allowlist or add the wallet address at https://www.coinbase.com/settings/allowlist 2. Wait approximately 2 days for updates to take effect. recipient_allowlist_pending: >- This error occurs when the user is not allowed to receive funds at this address, because changes to their coinbase account allowlist are pending. **Steps to resolve:** 1. Wait approximately 2 days for updates to take effect. refund_expired: >- Returned when a refund attempt is made after the payment session's refund deadline has passed. The payment session can no longer be refunded. travel_rules_recipient_violation: >- This error occurs when the user is not allowed to receive funds at this address, because it violates travel rules. **Steps to resolve:** 1. Ensure your desired transfer is not blocked by local travel regulations. mfa_already_enrolled: >- This error occurs when attempting to enroll in an MFA method that the user has already enrolled in. **Steps to resolve:** 1. Check if the user is already enrolled in the MFA method before initiating enrollment 2. To update or reset MFA, remove the existing enrollment first (if supported) 3. Use a different MFA method if multiple options are available mfa_invalid_code: >- This error occurs when the MFA code provided is incorrect or has already been used. **Steps to resolve:** 1. Verify the user entered the correct code from their authenticator app 2. Ensure the code is current (TOTP codes expire after 30 seconds) 3. Check that the device time is synchronized correctly 4. Ask the user to generate a new code and try again **Common causes:** - Typing errors in the 6-digit code - Using an expired TOTP code - Device clock drift on user's authenticator app - Attempting to reuse a previously submitted code mfa_flow_expired: >- This error occurs when the MFA enrollment or verification session has expired. **Steps to resolve:** 1. Restart the MFA enrollment or verification flow 2. Complete the flow within the allowed time window (typically 5 minutes) 3. Ensure the user doesn't leave the flow idle for extended periods **Note:** MFA sessions expire automatically for security purposes. mfa_required: >- This error occurs when attempting to perform a sensitive operation that requires MFA verification, but the user has not completed MFA verification. **Steps to resolve:** 1. Initiate the MFA verification flow using the `/mfa/verify/{mfaMethod}/init` endpoint 2. Prompt the user to enter their MFA code 3. Submit the verification using the `/mfa/verify/{mfaMethod}/submit` endpoint 4. Use the returned access token with MFA claim for the sensitive operation 5. Retry the original request with the new MFA-verified token **Operations requiring MFA:** - Transactions Sign/Send - Key export - Account management actions (when configured) mfa_not_enrolled: >- This error occurs when attempting to verify MFA for a user who has not enrolled in any MFA method. **Steps to resolve:** 1. Check if the user has enrolled in MFA before attempting verification 2. Guide the user through MFA enrollment first using the `/mfa/enroll/{mfaMethod}/init` endpoint 3. Complete enrollment before requiring MFA verification source_account_invalid: >- This error occurs when the source account specified in the transfer request is invalid or malformed. **Steps to resolve:** 1. Verify the account ID format is correct (e.g., `account_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) 2. Ensure the account ID belongs to your CDP entity 3. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` **Common causes:** - Malformed account ID - Typo in the account ID target_account_invalid: >- This error occurs when the target account specified in the transfer request is invalid or malformed. **Steps to resolve:** 1. Verify the account ID format is correct (e.g., `account_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) 2. Ensure the account exists and can receive funds 3. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` **Common causes:** - Malformed account ID - Typo in the account ID source_account_not_found: >- This error occurs when the source account specified in the transfer does not exist. **Steps to resolve:** 1. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` target_account_not_found: >- This error occurs when the target account specified in the transfer does not exist. **Steps to resolve:** 1. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` source_asset_not_supported: >- This error occurs when the asset specified in the transfer source is not supported for this transfer type. **Steps to resolve:** 1. Check the list of supported assets for the source account type 2. Verify the asset symbol is correctly specified (e.g., `usdc`, `usdt`) **Common causes:** - Unsupported asset for the transfer route - Incorrect asset symbol target_asset_not_supported: >- This error occurs when the asset specified in the transfer target is not supported for this transfer type. **Steps to resolve:** 1. Check the list of supported assets for the target 2. Verify the asset symbol is correctly specified (e.g., `usdc`, `usdt`) 3. Ensure the target can receive this asset type **Common causes:** - Asset not supported by the target - Unsupported conversion between source and target assets target_email_invalid: >- This error occurs when the email address specified as the transfer target is invalid. **Steps to resolve:** 1. Verify the email address format is valid (e.g., `user@example.com`) 2. Check for typos in the email address 3. Ensure the email domain is valid **Common causes:** - Invalid email format - Missing @ symbol or domain - Typo in the email address target_onchain_address_invalid: >- This error occurs when the onchain address specified as the transfer target is invalid for the specified network. **Steps to resolve:** 1. Ensure the network is supported for the transfer type 2. Verify the address format matches the target network 3. Ensure you haven't mixed up addresses from different networks **Common causes:** - Network not supported for the transfer type - Address format doesn't match network - Address from a different blockchain network transfer_amount_invalid: >- This error occurs when the transfer amount is invalid. **Steps to resolve:** 1. Ensure the amount is a positive number and greater than $1 USD equivalent amount 2. Verify the amount format is a valid decimal string (e.g., `"100.50"`) 3. Check the number of decimal places for the asset **Common causes:** - Zero or negative amount - Too many decimal places for the asset - Amount below minimum threshold ($1 USD equivalent amount) transfer_asset_not_supported: >- This error occurs when the asset specified for the transfer is not supported. **Steps to resolve:** 1. Check the list of supported assets for transfers 2. Verify the asset symbol is correctly specified 3. Ensure the asset is supported for the transfer route (source → target) **Common causes:** - Asset not supported for transfers - Incorrect asset symbol transfer_quote_expired: >- This error occurs when the transfer quote has expired. Quotes are valid for a limited time. **Steps to resolve:** 1. Create a new transfer to obtain a fresh quote 2. Execute the transfer promptly after creation **Common causes:** - Too much time elapsed between creating and executing the transfer insufficient_balance: >- This error occurs when the source account does not have enough funds to complete the transfer including fees. **Steps to resolve:** 1. Check the source account balance 2. Ensure the balance covers both the transfer amount and any fees 3. Consider using `amountType: "source"` to transfer the maximum available amount minus fees 4. Add funds to the source account if needed **Common causes:** - Transfer amount exceeds available balance - Not accounting for transfer fees - Pending transactions reducing available balance metadata_too_many_entries: >- This error occurs when the transfer metadata contains more entries than allowed. **Steps to resolve:** 1. Reduce the number of metadata entries (maximum 10 allowed) 2. Consolidate related data into fewer keys 3. Store additional data externally and reference it with a single metadata entry **Limits:** - Maximum entries: 10 metadata_key_too_long: >- This error occurs when a metadata key exceeds the maximum allowed length. **Steps to resolve:** 1. Shorten the metadata key to 40 characters or less 2. Use abbreviations or shorter naming conventions 3. Consider using a key-value structure where the value contains the longer identifier **Limits:** - Maximum key length: 40 characters metadata_value_too_long: >- This error occurs when a metadata value exceeds the maximum allowed length. **Steps to resolve:** 1. Shorten the metadata value to 500 characters or less 2. Store longer data externally and reference it with a shorter identifier 3. Consider compressing or encoding the data if appropriate **Limits:** - Maximum value length: 500 characters travel_rules_field_missing: >- This error occurs when required travel rule fields are missing from the transfer request. **Steps to resolve:** 1. Include the `travelRule` object in your transfer request 2. Supply the required missing fields prompted by the error message 3. Review the travel rule requirements for your jurisdiction Note: Required fields may vary by region. asset_mismatch: >- This error occurs when the assets specified in the transfer are incompatible or don't match expected values. **Steps to resolve:** 1. Ensure the `asset` field matches either the source or target asset 2. Verify that the source and target assets are compatible for conversion (if different) 3. Check that the asset symbols are correctly specified **Common causes:** - Transfer asset doesn't match source or target - Attempting an unsupported asset conversion - Typo in asset symbols order_quote_expired: >- This error occurs when attempting to execute an order whose quote has expired. **Steps to resolve:** 1. Create a new order with `execute: false` to get an updated quote. 2. Execute the new order before the quote expires (check the `expiresAt` field). 3. Alternatively, create a new order with `execute: true` to skip the quote step and execute immediately. order_already_filled: >- This error occurs when attempting to cancel or modify an order that has already been filled. **Steps to resolve:** 1. Check the current status of the order using `GET /v2/orders/{orderId}`. 2. A filled order cannot be canceled or re-executed. order_already_canceled: >- This error occurs when attempting to cancel or execute an order that has already been canceled. **Steps to resolve:** 1. Check the current status of the order using `GET /v2/orders/{orderId}`. 2. Create a new order if you still want to trade. account_not_ready: >- This error occurs when an operation is attempted on an account that is still being provisioned. **Steps to resolve:** 1. Wait a few moments and retry the request 2. If the error persists, the account may still be completing setup — retry with exponential backoff insufficient_liquidity: >- This error occurs when no swap route is available for the requested token pair or amount. **Steps to resolve:** 1. Try a smaller `fromAmount` — large orders may exceed available liquidity 2. Try a different token pair 3. Retry after a short delay; liquidity conditions change with market activity insufficient_allowance: >- This error occurs when the taker has not approved the Permit2 contract to spend the `fromToken` on their behalf. ERC-20 swaps require a Permit2 allowance. Native ETH swaps do not. **Steps to resolve:** 1. Submit an ERC-20 `approve` transaction on the `fromToken` contract, granting the Permit2 contract (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) an allowance of at least `fromAmount` 2. Wait for the approval transaction to be confirmed on-chain 3. Retry the swap **Example:** ```typescript lines wrap // Approve Permit2 to spend fromToken await walletClient.writeContract({ address: fromToken, abi: erc20Abi, functionName: "approve", args: ["0x000000000022D473030F116dDEE9F6B43aC78BA3", fromAmount], }); ``` transaction_simulation_failed: >- This error occurs when the pre-broadcast simulation of the swap transaction predicted a revert. No transaction was submitted and no gas was spent. **Common causes:** - The on-chain price moved past the `slippageBps` tolerance between the price estimate and execution - Taker balance changed between the price estimate and execution **Steps to resolve:** 1. Retry immediately — prices change quickly and a new quote may succeed 2. Increase `slippageBps` if retries continue to fail (e.g. from 100 to 200) 3. For large swaps, consider splitting into smaller amounts to reduce price impact delegation_not_found: >- This error occurs when a delegated signing operation is attempted but no active delegation grant exists for the end user (or account). **Steps to resolve:** 1. Create a delegation grant using `createDelegationForEndUser` (user-scoped) or `createDelegationForEndUserAccount` (account-scoped) before calling the signing or sending operation 2. If you previously created a grant, it may have expired or been revoked — in those cases you would receive a `delegation_expired` or `delegation_revoked` error instead 3. For account-scoped grants, verify the address in the request matches the granted address (EVM addresses are compared case-insensitively; Solana addresses must match exactly) delegation_expired: >- This error occurs when the delegation grant used for signing has expired. Delegation grants have a limited lifetime set at creation. **Steps to resolve:** 1. Create a new delegation grant using `createDelegationForEndUser` or `createDelegationForEndUserAccount` 2. Retry the signing operation with the new grant active 3. Consider creating grants with a longer TTL if expiry is frequent delegation_revoked: >- This error occurs when the delegation grant has been explicitly revoked. **Steps to resolve:** 1. Create a new delegation grant using `createDelegationForEndUser` or `createDelegationForEndUserAccount` 2. Confirm with the end user before recreating, since revocation is typically intentional delegation_not_authorized: >- This error occurs when a delegation grant exists but does not authorize the requested operation. **Steps to resolve:** 1. For account-scoped grants, verify the signing address matches the address the grant was created for 2. Check that the operation is permitted for delegated signing on your project 3. Create a grant with the correct scope if needed delegation_not_enabled: >- This error occurs when delegated signing is attempted on a project that has not enabled the feature. **Steps to resolve:** 1. Enable delegated signing in your project configuration via the CDP Portal 2. Contact support if you believe delegated signing should already be enabled for your project network_mismatch: >- This error occurs when the requested operation specifies a network on which the target resource is not deployed or not available. **Steps to resolve:** 1. Use the network the resource was originally created or deployed on 2. Check the resource metadata to confirm the correct network **Common causes:** - Specifying `base` for a resource that only exists on `base-sepolia` (or vice versa) - Cross-network operation attempted on a resource scoped to a single network already_enabled: >- This error occurs when the requested operation cannot be performed because the capability is already in the desired state. **Steps to resolve:** 1. Check the current state of the resource before attempting the operation 2. No action is needed if the resource is already in the desired state **Common causes:** - Calling an enable endpoint on a resource that already has the feature enabled Url: type: string format: uri minLength: 11 maxLength: 2048 pattern: ^https?://.*$ description: A valid HTTP or HTTPS URL. example: https://example.com CapabilityName: type: string description: > The name of a capability. Capabilities represent granular functional permissions that determine what actions a customer can perform. Each capability must be explicitly requested before use. enum: - custodyCrypto - custodyFiat - custodyStablecoin - tradeCrypto - tradeStablecoin - transferCrypto - transferFiat - transferStablecoin example: custodyCrypto Error: description: >- An error response including the code for the type of error and a human-readable message describing the error. type: object properties: errorType: $ref: '#/components/schemas/ErrorType' errorMessage: description: The error message. type: string example: Unable to create EVM account correlationId: description: >- A unique identifier for the request that generated the error. This can be used to help debug issues with the API. type: string example: 41deb8d59a9dc9a7-IAD errorLink: allOf: - $ref: '#/components/schemas/Url' description: A link to the corresponding error documentation. example: >- https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request unauthorizedCapabilities: description: > The capability code(s) that were not authorized for the customer on this request. Present only when `errorType` is `customer_not_authorized`; absent for every other error type. Use this list to render onboarding UX for the listed capabilities, or fetch `GET /v2/customers/{customerId}` and inspect each entry's `status` / `requirements` to discover what (if anything) can be submitted to resolve the block. type: array items: $ref: '#/components/schemas/CapabilityName' required: - errorType - errorMessage example: errorType: invalid_request errorMessage: Invalid request. correlationId: 41deb8d59a9dc9a7-IAD errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request CreateAccountRequest: type: object properties: name: $ref: '#/components/schemas/AccountName' Asset: type: string minLength: 1 maxLength: 42 description: The symbol of the asset (e.g., eth, usd, usdc, usdt). example: usd AssetType: type: string description: The type of the asset. enum: - fiat - crypto example: crypto balances_Asset: type: object description: An asset, e.g. fiat or crypto. properties: symbol: $ref: '#/components/schemas/Asset' type: $ref: '#/components/schemas/AssetType' name: type: string description: The name of the asset. decimals: type: integer description: >- The number of decimals (i.e. significant digits to the right of the decimal point) supported for the asset. required: - symbol - type - name - decimals example: symbol: btc type: crypto name: Bitcoin decimals: 8 AmountDetail: type: object description: Available and total amounts for a specific currency. properties: available: type: string description: The amount that is currently available to be used. example: '2.5' total: type: string description: The total amount, including the amount that is currently on hold. example: '3.0' required: - available - total Balance: type: object description: A balance of an asset. properties: asset: $ref: '#/components/schemas/balances_Asset' amount: type: object description: >- Amount details denominated in different assets. - The keys represent the asset symbols (e.g., "btc", "usd"), - Each value contains available and total amounts. - There will always be an entry for the asset specified in the `asset` field. additionalProperties: $ref: '#/components/schemas/AmountDetail' required: - asset - amount example: asset: symbol: btc type: crypto name: Bitcoin decimals: 8 amount: btc: available: '2.5' total: '3.0' usd: available: '252705.4' total: '303246.48' Balances: type: object description: A list of balances for an account. properties: balances: type: array description: The list of balances. items: $ref: '#/components/schemas/Balance' example: - asset: symbol: btc type: crypto name: Bitcoin decimals: 8 amount: btc: available: '2.5' total: '3.0' usd: available: '252705.4' total: '303246.48' required: - balances example: balances: - asset: symbol: btc type: crypto name: Bitcoin decimals: 8 amount: btc: available: '2.5' total: '3.0' usd: available: '252705.4' total: '303246.48' - asset: symbol: usd type: fiat name: United States Dollar decimals: 2 amount: usd: available: '90' total: '100' DepositDestinationType: type: string description: The type of deposit destination. oneOf: - enum: - crypto example: crypto DepositDestinationId: type: string pattern: ^depositDestination_[a-f0-9\-]{36}$ description: >- The ID of the Deposit Destination, which is a UUID prefixed by the string `depositDestination_`. example: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 Network: type: string description: >- The blockchain network for the payment. Supported networks depend on the account type. See [API and Network Support](https://docs.cdp.coinbase.com/api-reference/payment-apis/supported-networks-assets#by-asset-and-network) for more details. enum: - base - ethereum - solana - aptos - arbitrum - arbitrum-sepolia - optimism - polygon - world - world-sepolia example: base BlockchainAddress: type: string minLength: 1 maxLength: 128 description: >- A blockchain address. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana). example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' DepositDestinationCrypto: type: object description: >- Crypto-specific deposit destination details. In responses, this object is always present. Contains the network and address for the deposit destination. properties: network: $ref: '#/components/schemas/Network' address: $ref: '#/components/schemas/BlockchainAddress' required: - network - address example: network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' DepositDestinationTargetAccount: type: object title: Target Account description: The account and asset where incoming deposits should be credited. additionalProperties: false properties: accountId: allOf: - $ref: '#/components/schemas/AccountId' description: >- The ID of the CDP Account to which deposited funds should be transferred. asset: allOf: - $ref: '#/components/schemas/Asset' description: The symbol of the asset that should land in the target account. example: usd required: - asset example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd DepositDestinationTarget: description: The intended target for deposited funds. oneOf: - $ref: '#/components/schemas/DepositDestinationTargetAccount' DepositDestinationStatus: type: string description: The status of the deposit destination. enum: - active - inactive - pending example: active Metadata: type: object description: >- Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters. additionalProperties: type: string minLength: 0 maxLength: 500 maxProperties: 10 example: customer_id: cust_12345 order_reference: order-67890 CryptoDepositDestination: type: object description: A cryptocurrency deposit destination. properties: depositDestinationId: $ref: '#/components/schemas/DepositDestinationId' accountId: $ref: '#/components/schemas/AccountId' type: type: string description: The type of deposit destination. enum: - crypto example: crypto crypto: allOf: - $ref: '#/components/schemas/DepositDestinationCrypto' description: >- Crypto-specific details for this deposit destination. Always populated in responses. Contains the network and address. target: $ref: '#/components/schemas/DepositDestinationTarget' status: $ref: '#/components/schemas/DepositDestinationStatus' metadata: $ref: '#/components/schemas/Metadata' createdAt: type: string format: date-time description: The timestamp when the deposit destination was created. example: '2023-10-08T14:30:00Z' updatedAt: type: string format: date-time description: The timestamp when the deposit destination was last updated. example: '2023-10-08T14:30:00Z' required: - depositDestinationId - accountId - type - crypto - status - createdAt - updatedAt example: depositDestinationId: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto crypto: network: base address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' target: accountId: account_bf3847c1-a957-5ae8-cfa0-ddd33e046225 asset: usd status: active metadata: customer_id: 123e4567-e89b-12d3-a456-426614174000 reference: order-12345 createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' DepositDestination: description: A deposit destination for receiving funds to an account. oneOf: - $ref: '#/components/schemas/CryptoDepositDestination' discriminator: propertyName: type mapping: crypto: '#/components/schemas/CryptoDepositDestination' CreateDepositDestinationRequestBase: type: object description: Common fields for creating a deposit destination. properties: accountId: description: >- The ID of the Account, which is a UUID prefixed by the string `account_`, that owns the deposit destination. $ref: '#/components/schemas/AccountId' type: $ref: '#/components/schemas/DepositDestinationType' target: $ref: '#/components/schemas/DepositDestinationTarget' metadata: $ref: '#/components/schemas/Metadata' required: - accountId - type example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd CreateDepositDestinationCrypto: type: object description: Crypto-specific details for creating a deposit destination. properties: network: $ref: '#/components/schemas/Network' required: - network example: network: base CreateCryptoDepositDestinationRequest: allOf: - $ref: '#/components/schemas/CreateDepositDestinationRequestBase' - type: object properties: type: type: string enum: - crypto crypto: allOf: - $ref: '#/components/schemas/CreateDepositDestinationCrypto' description: Crypto-specific details. Required when `type` is `crypto`. required: - crypto example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: crypto crypto: network: base target: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd metadata: customer_id: 123e4567-e89b-12d3-a456-426614174000 reference: order-12345 CreateDepositDestinationRequest: description: >- Request to create a new deposit destination. Provide the type-specific details matching the chosen `type`. discriminator: propertyName: type mapping: crypto: '#/components/schemas/CreateCryptoDepositDestinationRequest' oneOf: - $ref: '#/components/schemas/CreateCryptoDepositDestinationRequest' TransferStatus: type: string description: >- The current status of the transfer, indicating what action you need to take next. Required when validateOnly is false. enum: - quoted - processing - completed - failed example: quoted x-enum-descriptions: - >- Transfer was created with `execute: true`, but is momentarily being quoted before executing _or_ the transfer was created with `execute: false`. It can be executed by calling `/v2/transfers/{transferId}/execute` with `execute: true`. - >- Transfer is executing after being quoted. No action needed - monitor progress via the transfers webhook. - Transfer completed successfully. - Transfer failed. See `failureReason` for details. Email: type: string format: email maxLength: 254 description: >- An email address. Maximum length 254 characters per [RFC 5321](https://www.rfc-editor.org/rfc/rfc5321). example: user@example.com transfers_Account: type: object title: Account description: The Account specific details for the transfer. properties: accountId: type: string description: The ID of the Account. asset: $ref: '#/components/schemas/Asset' required: - accountId - asset example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd PaymentMethod: type: object title: Payment Method description: The Payment Method specific details for the transfer. properties: paymentMethodId: type: string description: The ID of the Payment Method. asset: $ref: '#/components/schemas/Asset' required: - paymentMethodId - asset example: paymentMethodId: pm_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd OnchainAddress: type: object title: Onchain Address description: The target of the payment is an onchain address. properties: address: allOf: - $ref: '#/components/schemas/BlockchainAddress' description: | The onchain crypto address of the recipient. Examples: - EVM address: 0xabc1234567890abcdef1234567890abcdef123456 - Solana address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT - XRP address: rhccc5p23aKiCGFcEqqnjEfLRZ6xEvfy3s network: $ref: '#/components/schemas/Network' destinationTag: type: string description: > The destination tag of the onchain address. Destination tags are used by certain networks (primarily XRP/Ripple) to identify specific recipients when multiple users share a single address. The tag ensures funds are credited to the correct account within the shared address. Examples by network: - XRP/Ripple: Numeric values like "1234567890" or "123456" - Stellar (XLM): Memos which can be text, ID, or hash format Note: Most networks (Ethereum, Bitcoin, Solana) do not use destination tags. asset: allOf: - $ref: '#/components/schemas/Asset' description: Asset symbol of the payment received by the recipient. example: btc required: - address - network - asset example: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base asset: usdc OriginatingBankAccountUS: type: object title: Originating Bank Account (US) description: >- The originating US bank account details for the transfer source. Present when funds were deposited from an external bank account into a deposit destination. Only the last 4 digits of the account number are exposed. properties: bankName: type: string description: The name of the bank that originated the deposit. example: Citibank, N.A. accountLast4: type: string description: The last 4 digits of the originating bank account number. pattern: ^[0-9]{4}$ example: '6789' currency: type: string description: The fiat currency of the deposit (e.g., `usd`). example: usd required: - bankName - accountLast4 - currency example: bankName: Citibank, N.A. accountLast4: '6789' currency: usd TransferSource: description: The source of the transfer. oneOf: - $ref: '#/components/schemas/transfers_Account' - $ref: '#/components/schemas/PaymentMethod' - $ref: '#/components/schemas/OnchainAddress' - $ref: '#/components/schemas/OriginatingBankAccountUS' example: {} EmailAddress: type: object title: Email Address description: The target of the payment is an email address. properties: email: allOf: - $ref: '#/components/schemas/Email' description: >- The email address of the recipient. The recipient will need to have an account with Coinbase or onboard to Coinbase to receive the payment. example: recipient@example.com required: - email example: email: recipient@example.com EmailInstrument: title: Email Instrument description: The target of the payment is an email address. allOf: - $ref: '#/components/schemas/EmailAddress' - type: object properties: asset: allOf: - $ref: '#/components/schemas/Asset' description: Asset symbol of the payment received by the recipient. required: - asset example: email: recipient@example.com asset: usd TransferTarget: description: The target of the transfer. oneOf: - $ref: '#/components/schemas/transfers_Account' - $ref: '#/components/schemas/PaymentMethod' - $ref: '#/components/schemas/OnchainAddress' - $ref: '#/components/schemas/EmailInstrument' example: {} TransferExchangeRate: type: object description: >- Exchange rate information for currency conversion. The rate indicates how much of the target asset is equivalent to one unit of the source asset. properties: sourceAsset: allOf: - $ref: '#/components/schemas/Asset' description: The asset being converted from. example: usd targetAsset: allOf: - $ref: '#/components/schemas/Asset' description: The asset being converted to. example: usdc rate: type: string description: >- The exchange rate value as a decimal string. Indicates how many units of the target asset equal one unit of the source asset. example: '1' required: - sourceAsset - targetAsset - rate example: sourceAsset: usd targetAsset: usdc rate: '1' TransferFee: type: object description: A single fee for a transfer. properties: type: type: string description: The type of the fee, indicating its purpose. enum: - bank - conversion - network - other x-enum-varnames: - BankFee - ConversionFee - NetworkFee - OtherFee example: network amount: type: string description: The amount of the fee in units of the asset specified by `asset`. example: '1500000' asset: allOf: - $ref: '#/components/schemas/Asset' description: The asset symbol. example: usd required: - type - amount - asset TransferFees: type: array description: >- The fees associated with this transfer. Different transfer types have different fee structures. **NOTE:** These examples are not exhaustive. Common examples: * **Crypto transfers**: Network fees (gas) paid in the native token * **Fiat conversions**: Processing fees + exchange fees in USD * **Wire transfers**: Wire fees ($15) + processing fees ($5) in USD * **Crypto conversions**: Spread fees paid in the source asset. example: - type: bank amount: '20' asset: usd - type: conversion amount: '1.00' asset: usdc - type: network amount: '0.01' asset: usdc items: $ref: '#/components/schemas/TransferFee' TransferEstimate: type: object description: >- A point-in-time snapshot of estimated values for a transfer where exact amounts cannot be locked in at quote time (e.g., when the executed rate is determined at execution time and moves with the market). Present in both pre-execution and post-execution states: * **Quoted state:** top-level fields whose values cannot be guaranteed are absent; `estimate` holds their estimated values. * **Completed state:** top-level fields contain the actual executed values; `estimate` is retained as an immutable audit snapshot of the pre-execution estimate. properties: exchangeRate: $ref: '#/components/schemas/TransferExchangeRate' targetAmount: type: string description: >- Estimated amount of the target asset that will be received, as a decimal string in standard unit denomination. example: '85.00' targetAsset: allOf: - $ref: '#/components/schemas/Asset' description: The asset symbol of the estimated target amount. example: eur fees: $ref: '#/components/schemas/TransferFees' estimatedAt: type: string format: date-time description: The date and time when this estimate was captured. example: '2023-10-08T14:30:00Z' required: - estimatedAt example: exchangeRate: sourceAsset: usdc targetAsset: eur rate: '0.85' targetAmount: '85.00' targetAsset: eur fees: - type: conversion amount: '0.01' asset: usdc estimatedAt: '2023-10-08T14:30:00Z' DepositDestinationReference: type: object description: A reference to the deposit destination associated with the transfer. properties: id: $ref: '#/components/schemas/DepositDestinationId' required: - id example: id: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 TravelRuleStatus: type: string description: The status of a travel rule submission. enum: - incomplete - completed x-enum-varnames: - TravelRuleStatusIncomplete - TravelRuleStatusCompleted x-enum-descriptions: - Additional fields are required before the transfer can proceed. - All requirements are satisfied and the transfer will proceed. example: incomplete TransferDetails: type: object description: >- Additional details about the transfer. For example, if the transfer was sent to a deposit destination, the information about that destination will be included in this field. properties: depositDestination: $ref: '#/components/schemas/DepositDestinationReference' onchainTransactions: type: array description: The onchain transactions associated with the transfer. items: type: object description: An onchain transaction associated with the transfer. properties: transactionHash: type: string description: The transaction hash. example: >- 0x363cd3b3d4f49497cf5076150cd709307b90e9fc897fdd623546ea7b9313cecb network: $ref: '#/components/schemas/Network' required: - transactionHash - network example: - transactionHash: >- 0x363cd3b3d4f49497cf5076150cd709307b90e9fc897fdd623546ea7b9313cecb network: base travelRule: type: object description: >- Travel rule compliance status for deposit transfers. Present when the transfer requires travel rule information. properties: status: $ref: '#/components/schemas/TravelRuleStatus' statusMessage: type: string description: >- Additional details about the current travel rule status. For example, when status is `incomplete`, this may indicate the specific missing information required to proceed. example: Originator date of birth is required. example: status: incomplete statusMessage: Originator date of birth is required. example: depositDestination: id: depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114 onchainTransactions: - transactionHash: '0x363cd3b3d4f49497cf5076150cd709307b90e9fc897fdd623546ea7b9313cecb' network: base Transfer: type: object description: >- A Transfer represents all the information needed to execute a transfer and tracks the lifecycle of a transfer from initiation through completion or failure. properties: transferId: type: string description: The ID of the transfer. Required when validateOnly is false. example: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: $ref: '#/components/schemas/TransferStatus' source: $ref: '#/components/schemas/TransferSource' target: $ref: '#/components/schemas/TransferTarget' sourceAmount: type: string description: >- The amount of the source asset that will be transferred out, as a decimal string in standard unit denomination. example: '103.50' sourceAsset: allOf: - $ref: '#/components/schemas/Asset' description: The asset symbol of the source amount. example: usd targetAmount: type: string description: >- The amount of the target asset that will be received, as a decimal string in standard unit denomination. example: '100.00' targetAsset: allOf: - $ref: '#/components/schemas/Asset' description: The asset symbol of the target amount. example: usdc exchangeRate: $ref: '#/components/schemas/TransferExchangeRate' fees: $ref: '#/components/schemas/TransferFees' estimate: $ref: '#/components/schemas/TransferEstimate' completedAt: type: string format: date-time description: The date and time the transfer was completed. example: '2025-01-01T00:05:00Z' failureReason: type: string description: >- The reason for failure, if the transfer failed. Only present when status is `failed`. example: Insufficient balance to complete this transfer. expiresAt: type: string format: date-time description: >- The date and time when this transfer will expire if not executed. Only present for `quoted` status. A new transfer must be created to obtain an updated quote after expiration. Required when validateOnly is false. example: '2025-01-01T00:15:00Z' executedAt: type: string format: date-time description: >- The date and time the transfer was executed and moved to processing. Only present when status has progressed beyond `quoted`. example: '2025-01-01T00:01:30Z' createdAt: type: string format: date-time description: >- The date and time the transfer was created. Required when validateOnly is false. example: '2025-01-01T00:00:00Z' updatedAt: type: string format: date-time description: >- The date and time the transfer was last updated. Required when validateOnly is false. example: '2025-01-01T00:00:00Z' metadata: $ref: '#/components/schemas/Metadata' details: $ref: '#/components/schemas/TransferDetails' required: - source - target example: transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: completed source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base asset: usdc sourceAmount: '103.50' sourceAsset: usd targetAmount: '100.00' targetAsset: usdc completedAt: '2025-01-01T00:05:00Z' createdAt: '2025-01-01T00:00:00Z' updatedAt: '2025-01-01T00:05:00Z' CreateTransferSource: description: The source of the transfer. oneOf: - $ref: '#/components/schemas/transfers_Account' - $ref: '#/components/schemas/PaymentMethod' example: {} PhysicalAddress: type: object description: >- A physical address with standard address components including street, city, state/province, postal code, and country. properties: line1: type: string description: Primary street address. example: 123 Market St line2: type: string description: Secondary address information. example: Suite 400 city: type: string description: City or locality. example: San Francisco state: type: string description: State, province, or region. example: CA postCode: type: string description: Postal or ZIP code. example: '94105' countryCode: type: string minLength: 2 maxLength: 2 description: >- ISO 3166-1 alpha-2 country code (2 characters). See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes. example: US TravelRuleParty: type: object description: >- Information about a party (originator or beneficiary) for travel rule compliance. properties: financialInstitution: type: string description: Name of the financial institution. example: PayPal, Inc. name: type: string description: Full name of the party. example: John Doe address: $ref: '#/components/schemas/PhysicalAddress' example: name: John Doe address: line1: 123 Main St line2: Unit 201 city: San Francisco state: California postCode: '94105' countryCode: US PersonalIdentification: type: object description: >- A government-issued personal identifier, paired with its type and issuing country so downstream Travel Rule reporting can classify the identifier correctly. Field shapes mirror IVMS-101 `NationalIdentification` (the format Travel Rule reporting ultimately marshals to) — most notably the 35-character maximum on `value`. properties: type: type: string description: >- The kind of government-issued identifier carried in `value`. Values map 1:1 to IVMS-101 `NationalIdentifierTypeCode` so downstream Travel Rule reporting can serialize without ambiguity. enum: - social_security_number - tax_id - passport_number - national_id_card - drivers_license x-enum-descriptions: - >- Social security or equivalent national insurance number (IVMS-101 `SOCS`). For US: full SSN; for LU: matricule national. - >- Tax authority identifier (IVMS-101 `TXID`). E.g. US ITIN, BR CPF, IN PAN. - Passport number (IVMS-101 `CCPT`). - State-issued identity card number (IVMS-101 `IDCD`). - Driver's license number (IVMS-101 `DRLC`). example: social_security_number value: type: string description: >- The identifier as issued by the relevant authority. Length matches the IVMS-101 `NationalIdentifier` 35-character cap. Letters, digits, and common separators (hyphens, spaces, dots) are accepted; the exact character set depends on `type` and `countryOfIssue`. minLength: 1 maxLength: 35 example: 123-45-6789 countryOfIssue: type: string description: >- ISO 3166-1 alpha-2 country code of the authority that issued the identifier. Required when the identifier format depends on the issuing jurisdiction (e.g. a "national ID" means different things in DE vs. BR). minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ example: US required: - type - value example: type: social_security_number value: 123-45-6789 countryOfIssue: US DateOfBirth: type: object description: Date of birth. properties: day: type: string description: Day of birth (01-31). minLength: 2 maxLength: 2 pattern: ^[0-9]{2}$ example: '15' month: type: string description: Month of birth (01-12). minLength: 2 maxLength: 2 pattern: ^[0-9]{2}$ example: '08' year: type: string description: Year of birth (four digits). minLength: 4 maxLength: 4 pattern: ^[0-9]{4}$ example: '1990' example: day: '15' month: '08' year: '1990' TravelRuleOriginator: allOf: - $ref: '#/components/schemas/TravelRuleParty' - type: object properties: virtualAssetServiceProvider: type: object description: >- Information about the originating Virtual Asset Service Provider (VASP) that handles cryptocurrency or other virtual assets on behalf of customers. properties: name: type: string description: >- The name of the originating Virtual Asset Service Provider (VASP). example: Fidelity Digital Asset Services, LLC address: description: >- The address of the originating Virtual Asset Service Provider (VASP). $ref: '#/components/schemas/PhysicalAddress' identifier: type: string description: >- The Legal Entity Identifier of the originating Virtual Asset Service Provider (VASP). example: 5493001KJTIIGC8Y1R17 personalIdentification: allOf: - $ref: '#/components/schemas/PersonalIdentification' description: >- Government-issued personal identification for the originator, carrying the identifier value, its type, and the issuing country. Required for transfers originating from certain jurisdictions (such as Coinbase Luxembourg) to satisfy Travel Rule reporting obligations. example: type: social_security_number value: 123-45-6789 countryOfIssue: US dateOfBirth: allOf: - $ref: '#/components/schemas/DateOfBirth' description: >- Date of birth of the originator. Required by certain jurisdictions (such as Coinbase Luxembourg) to satisfy Travel Rule reporting obligations. example: day: '15' month: '08' year: '1990' description: Originator (sender) party. TravelRuleBeneficiary: allOf: - $ref: '#/components/schemas/TravelRuleParty' - type: object properties: walletType: type: string description: The type of the beneficiary's wallet. enum: - custodial - self_custody example: custodial description: Beneficiary (receiver) party. TravelRule: type: object description: >- Required Travel Rule fields differ by region. These requirements are determined based on which Coinbase entity the customer has signed the service agreement for. properties: isSelf: type: boolean description: >- Indicates whether the user attests that the receiving wallet belongs to them. example: true isIntermediary: type: boolean description: > Indicates whether Coinbase is being used as an intermediary Virtual Asset Service Provider (VASP) to send crypto on behalf of your customer. **Background:** The Travel Rule (FATF Recommendation 16) requires VASPs to share originator and beneficiary information for virtual asset transfers. When Coinbase acts as an intermediary, additional Travel Rule data must be provided to satisfy compliance requirements. **Set to `true` when:** - Your organization is a VASP using Coinbase to send crypto **on behalf of your end customer** - In this scenario, Coinbase acts as an intermediary in the transfer chain and handles Travel Rule data exchange with the beneficiary VASP **Set to `false` (or omit) when:** - You are transferring funds directly from your own Coinbase account, where **Coinbase is your primary VASP** rather than an intermediary for another institution **Impact on required fields:** When `isIntermediary` is `true`, you must provide the `originator` object with details about the **original sender**, including: - Originator name - Originator address - Your VASP information (`virtualAssetServiceProvider` object with `name`, `address`, and `identifier`) For jurisdictions that require them (such as Coinbase Luxembourg), `personalIdentification` and `dateOfBirth` must also reflect the **original sender's** identity — not the intermediary's. These fields will not be auto-populated from any internal KYC data when `isIntermediary` is `true`. example: true originator: $ref: '#/components/schemas/TravelRuleOriginator' beneficiary: $ref: '#/components/schemas/TravelRuleBeneficiary' example: isSelf: false isIntermediary: true originator: name: John Doe address: line1: 123 Main St line2: Unit 201 city: San Francisco state: California postCode: '94105' countryCode: US financialInstitution: PayPal, Inc. vasp: name: Fidelity Digital Asset Services, LLC address: line1: 123 Market St line2: Suite 400 city: San Francisco state: California postCode: '94105' countryCode: US identifier: 5493001KJTIIGC8Y1R17 personalIdentification: type: social_security_number value: 123-45-6789 countryOfIssue: US dateOfBirth: day: '15' month: '08' year: '1990' beneficiary: name: Jane Smith address: line1: 456 Oak Ave city: Paris postCode: '75001' countryCode: FR walletType: custodial TransferRequest: type: object description: A request to create a transfer. properties: source: $ref: '#/components/schemas/CreateTransferSource' target: $ref: '#/components/schemas/TransferTarget' amount: type: string description: >- The amount of the transfer, as a decimal string in standard unit denomination of the asset specified by `asset` (e.g., "100.00" for 100 USD, "0.05" for 0.05 ETH). example: '100.00' asset: allOf: - $ref: '#/components/schemas/Asset' description: >- The symbol of the asset for the amount. This must be one of the assets of the source or target. example: usd amountType: type: string default: source description: > Specifies whether the given amount is to be received by the target or taken from the source. - `target`: The transfer `target` receives the exact value specified in `amount`. Fees are added to the amount taken from the transfer `source`. - `source`: The transfer `target` receives the value specified in `amount`, minus any fees. enum: - target - source example: source validateOnly: type: boolean default: false description: >- If true, validates the transfer without initiating it. If the request is valid, a 2xx will be returned. If the request is invalid, a 4xx error will be returned. The response will include an errorType, for e.g. invalid_target if the specified target cannot receive funds. example: false execute: type: boolean description: >- Whether to immediately execute the transfer. If false, the transfer will be created in quoted status and must be executed manually via the /execute endpoint. example: true metadata: $ref: '#/components/schemas/Metadata' travelRule: $ref: '#/components/schemas/TravelRule' required: - source - target - amount - asset - execute DepositTravelRuleVasp: type: object description: >- Information about the Virtual Asset Service Provider (VASP) for a deposit travel rule submission. properties: identifier: type: string description: >- The Legal Entity Identifier (LEI) of the Virtual Asset Service Provider (VASP). example: 5493001KJTIIGC8Y1R17 name: type: string description: The name of the Virtual Asset Service Provider (VASP). example: Fidelity Digital Asset Services, LLC example: identifier: 5493001KJTIIGC8Y1R17 name: Fidelity Digital Asset Services, LLC DepositTravelRuleOriginator: type: object description: Originator information for a deposit travel rule submission. properties: name: type: string description: Full name of the originator. example: John Doe address: $ref: '#/components/schemas/PhysicalAddress' walletType: type: string description: The type of the originator's wallet. enum: - custodial - self_custody x-enum-descriptions: - The originator's wallet is held by a custodial service. - The originator's wallet is self-custodied. example: custodial virtualAssetServiceProvider: $ref: '#/components/schemas/DepositTravelRuleVasp' personalIdentification: allOf: - $ref: '#/components/schemas/PersonalIdentification' description: >- Government-issued personal identification for the originator, carrying the identifier value, its type, and the issuing country. example: type: social_security_number value: 123-45-6789 countryOfIssue: US dateOfBirth: $ref: '#/components/schemas/DateOfBirth' example: name: John Doe address: line1: 123 Main St city: San Francisco state: CA postCode: '94105' countryCode: US walletType: custodial vasp: identifier: 5493001KJTIIGC8Y1R17 name: Fidelity Digital Asset Services, LLC DepositTravelRuleBeneficiary: type: object description: Beneficiary information for a deposit travel rule submission. properties: name: type: string description: Full name of the beneficiary. example: Jane Smith example: name: Jane Smith DepositTravelRuleRequest: type: object description: >- Request body for submitting travel rule information for a deposit transfer. Required fields vary by jurisdiction. properties: originator: $ref: '#/components/schemas/DepositTravelRuleOriginator' beneficiary: $ref: '#/components/schemas/DepositTravelRuleBeneficiary' isSelf: type: boolean description: >- Indicates whether the user attests that the originating wallet belongs to them. example: false example: originator: name: John Doe address: line1: 123 Main St city: San Francisco state: CA postCode: '94105' countryCode: US beneficiary: name: Jane Smith isSelf: false DepositTravelRuleResponse: type: object description: Response from submitting travel rule information for a deposit transfer. properties: status: $ref: '#/components/schemas/TravelRuleStatus' missingFields: type: array description: >- List of field paths that are still required to complete travel rule compliance. Each entry is a dot-separated path (e.g., "originator.name", "originator.address.countryCode"). Empty when status is "completed". items: type: string example: originator.name example: - originator.address.countryCode reason: type: string description: >- Additional context about the current status. Present when status is `incomplete` to explain what needs to be fixed before the transfer can proceed. example: Originator date of birth is required. required: - status example: status: incomplete missingFields: - originator.address.countryCode PaymentSessionId: type: string pattern: ^paymentSession_[a-f0-9\-]{36}$ description: The ID of the payment session, a UUID prefixed by `paymentSession_`. example: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad PaymentTargetNetwork: type: string description: >- The blockchain network supported for payment session targets. Testnet networks are only available in sandbox environments. enum: - base - base-sepolia example: base PaymentTargetWallet: type: object title: Payment Target Wallet description: >- A blockchain wallet address used as a payment target (merchant recipient). properties: address: allOf: - $ref: '#/components/schemas/BlockchainAddress' description: The blockchain address of the recipient. example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: allOf: - $ref: '#/components/schemas/PaymentTargetNetwork' description: The blockchain network for the payment. example: base required: - address example: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base PaymentSessionTarget: description: The target of the payment. oneOf: - $ref: '#/components/schemas/PaymentTargetWallet' - $ref: '#/components/schemas/transfers_Account' PaymentExpiries: type: object description: >- Deadlines for each stage of the payment session lifecycle. All fields are optional; when omitted from a create request, the following defaults apply: `authorizationExpiresAt` = now + 1 day, `captureExpiresAt` = now + 7 days, `refundExpiresAt` = now + 30 days. Expiries must satisfy `authorizationExpiresAt` ≤ `captureExpiresAt` ≤ `refundExpiresAt`. The API returns a 400 error if this constraint is violated. Each deadline acts as a guard — after it passes, the corresponding action is rejected, but the session remains in its current status. No automatic state transitions occur; the merchant must take explicit action (e.g., cancel or void) to move the session to a terminal state. properties: authorizationExpiresAt: type: string format: date-time description: >- The UTC ISO 8601 timestamp after which authorization attempts are rejected. Defaults to now + 1 day if omitted. The session remains in its current pre-authorization status; the merchant must explicitly cancel the session. example: '2025-12-31T23:59:59.000Z' captureExpiresAt: type: string format: date-time description: >- The UTC ISO 8601 timestamp after which capture attempts are rejected. Defaults to now + 7 days if omitted. The session remains in its current status; the merchant must explicitly void to release uncaptured funds. example: '2026-01-15T23:59:59.000Z' refundExpiresAt: type: string format: date-time description: >- The UTC ISO 8601 timestamp after which refund attempts are rejected. Defaults to now + 30 days if omitted. The session remains in its current status; the refund window is simply closed. example: '2026-02-15T23:59:59.000Z' example: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' PaymentSourceNetwork: type: string description: >- The blockchain network supported for payment session sources. Testnet networks are only available in sandbox environments. enum: - arbitrum - arbitrum-sepolia - base - base-sepolia - ethereum - ethereum-sepolia - optimism - optimism-sepolia - polygon - polygon-amoy example: base PaymentSourceWallet: type: object title: Payment Source Wallet description: A blockchain wallet address used as a payment source. properties: address: allOf: - $ref: '#/components/schemas/BlockchainAddress' description: The blockchain address of the payer. example: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: allOf: - $ref: '#/components/schemas/PaymentSourceNetwork' description: The blockchain network for the payment. example: base asset: allOf: - $ref: '#/components/schemas/Asset' description: The asset used for the payment. example: usdc required: - address example: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc PaymentSourceCoinbase: type: object title: Payment Source Coinbase description: A Coinbase account authenticated via OAuth, used as a payment source. properties: coinbaseUserId: type: string description: The unique identifier of the payer within Coinbase. example: coinbase_user_abc123 required: - coinbaseUserId PaymentSessionSource: description: >- The source of the payment. Can be either an onchain wallet address or a Coinbase account authenticated via OAuth. oneOf: - $ref: '#/components/schemas/PaymentSourceWallet' - $ref: '#/components/schemas/PaymentSourceCoinbase' example: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc PaymentSessionStatus: type: string description: >- The most recent meaningful event on the payment session. For session-level milestones the value is one of `created` or `canceled`. For action outcomes the value follows the pattern `{action}_{result}` — e.g. `authorization_succeeded`, `capture_pending`, `refund_failed`. enum: - created - canceled - authorization_pending - authorization_succeeded - authorization_failed - capture_pending - capture_succeeded - capture_failed - void_pending - void_succeeded - void_failed - refund_pending - refund_succeeded - refund_failed example: created PaymentSessionBalances: type: object description: >- Running totals tracking how funds move through the session. All amounts are decimal representations denominated in the session's `asset`. properties: capturable: type: string description: >- Authorized funds not yet captured or voided. Decreases with each capture or void. example: '1.00' captured: type: string description: Total funds captured across all captures. example: '0' refundable: type: string description: Captured funds not yet refunded. Equals `captured` minus `refunded`. example: '0' refunded: type: string description: Total funds refunded across all refunds. example: '0' example: capturable: '1.00' captured: '0' refundable: '0' refunded: '0' AuthorizationId: type: string pattern: ^authorization_[a-f0-9\-]{36}$ description: The ID of the authorization, a UUID prefixed by `authorization_`. example: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad PaymentActionStatus: type: string description: >- The current status of a payment action (authorization, capture, void, or refund). enum: - pending - succeeded - failed example: pending PaymentError: type: object description: An error that occurred during a payment operation. properties: code: type: string description: A machine-readable error code. example: insufficient_funds message: type: string description: A human-readable description of the error. example: The payer does not have sufficient funds. occurredAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the error occurred. example: '2025-06-15T12:00:00.000Z' example: code: insufficient_funds message: The payer does not have sufficient funds. occurredAt: '2025-06-15T12:00:00.000Z' OnchainTransaction: type: object description: An onchain transaction associated with a payment action. properties: transactionHash: type: string description: The blockchain transaction hash. example: '0xabc123def456789012345678901234567890abcdef1234567890abcdef123456' network: allOf: - $ref: '#/components/schemas/PaymentSourceNetwork' description: The blockchain network the transaction occurred on. example: base required: - transactionHash - network Authorization: type: object description: >- A hold placed on the payer's funds. Once authorized, the merchant can capture (collect) the funds. Only one authorization is allowed per session. properties: authorizationId: allOf: - $ref: '#/components/schemas/AuthorizationId' description: The unique identifier of the authorization. example: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: allOf: - $ref: '#/components/schemas/PaymentSessionId' description: The ID of the payment session this authorization belongs to. example: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: allOf: - $ref: '#/components/schemas/PaymentActionStatus' description: The current status of the authorization. example: pending amount: type: string description: >- A decimal representation of the authorized amount, denominated in the session's `asset`. example: '1.00' error: $ref: '#/components/schemas/PaymentError' message: type: string description: >- A human-readable message describing the outcome or status for display. Returned for x402 authorizations; omitted for other authorization flows unless documented otherwise. example: Your payment was successfully submitted metadata: $ref: '#/components/schemas/Metadata' source: allOf: - $ref: '#/components/schemas/PaymentSessionSource' description: >- The payer for this authorization. For wallet authorizations, this is the blockchain address that signed the payloads. For Coinbase authorizations, this is the authenticated Coinbase account. This value is also reflected on the parent payment session's `source` field after a successful authorization. example: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc onchainTransactions: type: array description: The onchain transactions associated with this authorization. items: $ref: '#/components/schemas/OnchainTransaction' example: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the authorization was created. example: '2025-06-15T12:00:00.000Z' updatedAt: type: string format: date-time description: >- The UTC ISO 8601 timestamp at which the authorization was last updated. example: '2025-06-15T12:01:00.000Z' example: authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc onchainTransactions: - transactionHash: '0xabc123def456789012345678901234567890abcdef1234567890abcdef123456' network: base metadata: customer_id: cust_12345 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:01:00.000Z' CaptureId: type: string pattern: ^capture_[a-f0-9\-]{36}$ description: The ID of the capture, a UUID prefixed by `capture_`. example: capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad Capture: type: object description: >- A collection of authorized funds. Multiple partial captures are allowed up to the authorized amount. Each capture settles funds to the merchant's target. properties: captureId: allOf: - $ref: '#/components/schemas/CaptureId' description: The unique identifier of the capture. example: capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: allOf: - $ref: '#/components/schemas/PaymentSessionId' description: The ID of the payment session this capture belongs to. example: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: allOf: - $ref: '#/components/schemas/PaymentActionStatus' description: The current status of the capture. example: pending amount: type: string description: >- A decimal representation of the captured amount, denominated in the session's `asset`. example: '1.00' finalCapture: type: boolean description: >- When `true`, this capture is treated as the final one for the authorization. Any remaining capturable balance is released back to the payer immediately after the capture settles. When `false`, the remaining capturable balance stays held and is available for subsequent partial captures (subject to `captureExpiresAt`). Has no effect if `amount` equals the full capturable balance, since no remaining balance exists to release. example: true error: $ref: '#/components/schemas/PaymentError' metadata: $ref: '#/components/schemas/Metadata' onchainTransactions: type: array description: The onchain transactions associated with this capture. items: $ref: '#/components/schemas/OnchainTransaction' example: - transactionHash: >- 0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678 network: base createdAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the capture was created. example: '2025-06-15T12:20:00.000Z' updatedAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the capture was last updated. example: '2025-06-15T12:21:00.000Z' required: - finalCapture example: captureId: capture_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' finalCapture: true onchainTransactions: - transactionHash: '0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678' network: base metadata: customer_id: cust_12345 createdAt: '2025-06-15T12:20:00.000Z' updatedAt: '2025-06-15T12:21:00.000Z' VoidId: type: string pattern: ^void_[a-f0-9\-]{36}$ description: The ID of the void, a UUID prefixed by `void_`. example: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad Void: type: object description: >- A release of uncaptured authorized funds back to the payer. Voids release all remaining capturable funds in a single operation, including after partial refunds as long as a capturableAmount remains. properties: voidId: allOf: - $ref: '#/components/schemas/VoidId' description: The unique identifier of the void. example: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: allOf: - $ref: '#/components/schemas/PaymentSessionId' description: The ID of the payment session this void belongs to. example: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: allOf: - $ref: '#/components/schemas/PaymentActionStatus' description: The current status of the void. example: pending amount: type: string description: >- A decimal representation of the voided amount, denominated in the session's `asset`. example: '1.00' error: $ref: '#/components/schemas/PaymentError' metadata: $ref: '#/components/schemas/Metadata' onchainTransactions: type: array description: The onchain transactions associated with this void. items: $ref: '#/components/schemas/OnchainTransaction' example: - transactionHash: >- 0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12 network: base createdAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the void was created. example: '2025-06-15T12:30:00.000Z' updatedAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the void was last updated. example: '2025-06-15T12:31:00.000Z' example: voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad status: succeeded amount: '1.00' onchainTransactions: - transactionHash: '0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12' network: base metadata: customer_id: cust_12345 createdAt: '2025-06-15T12:30:00.000Z' updatedAt: '2025-06-15T12:31:00.000Z' RefundId: type: string pattern: ^refund_[a-f0-9\-]{36}$ description: The ID of the refund, a UUID prefixed by `refund_`. example: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad RefundWallet: type: object title: Refund Wallet description: >- An onchain address from which funds are pulled to fund the refund. Network and asset are inferred from the payment session. properties: address: allOf: - $ref: '#/components/schemas/BlockchainAddress' description: The onchain crypto address from which to fund the refund. example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' required: - address RefundSource: oneOf: - $ref: '#/components/schemas/transfers_Account' - $ref: '#/components/schemas/RefundWallet' description: The source from which a refund is funded. Refund: type: object description: >- A return of previously captured funds to the payer. Multiple partial refunds are allowed up to the total captured amount. properties: refundId: allOf: - $ref: '#/components/schemas/RefundId' description: The unique identifier of the refund. example: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: allOf: - $ref: '#/components/schemas/PaymentSessionId' description: The ID of the payment session this refund belongs to. example: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: allOf: - $ref: '#/components/schemas/RefundSource' description: >- The source from which the refund is funded. Can be a CDP account or an onchain address. example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc status: allOf: - $ref: '#/components/schemas/PaymentActionStatus' description: The current status of the refund. example: pending amount: type: string description: >- A decimal representation of the refunded amount, denominated in the session's `asset`. example: '0.50' reason: type: string description: The reason for the refund. example: Customer returned the item. error: $ref: '#/components/schemas/PaymentError' metadata: $ref: '#/components/schemas/Metadata' onchainTransactions: type: array description: The onchain transactions associated with this refund. items: $ref: '#/components/schemas/OnchainTransaction' example: - transactionHash: >- 0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234 network: base createdAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the refund was created. example: '2025-06-15T12:40:00.000Z' updatedAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the refund was last updated. example: '2025-06-15T12:41:00.000Z' example: refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc status: succeeded amount: '0.50' reason: Customer returned the item. onchainTransactions: - transactionHash: '0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234' network: base metadata: customer_id: cust_12345 createdAt: '2025-06-15T12:40:00.000Z' updatedAt: '2025-06-15T12:41:00.000Z' PaymentRedirect: type: object description: >- Redirect URLs used to direct the payer after a web-based payment flow completes or fails. properties: failureUrl: allOf: - $ref: '#/components/schemas/Url' description: The URL to redirect the payer to on payment failure. example: https://merchant.example.com/payment/failed successUrl: allOf: - $ref: '#/components/schemas/Url' description: The URL to redirect the payer to on payment success. example: https://merchant.example.com/payment/success example: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success CustomerDisplay: type: object title: Customer Display description: >- Merchant-provided display data shown to the payer during checkout. All fields are informational only — stored and returned as-is, with no effect on payment processing, settlement, or validation. properties: merchantName: type: string maxLength: 128 description: >- The merchant name to display on the payment UI. When provided, this overrides the default name derived from the entity's profile. Useful when a merchant operates multiple storefronts or brands under a single entity. example: Acme Store displayAmount: type: object description: >- The amount to present to the payer, which may differ from the authoritative settlement amount and asset. Commonly used when the payer's local currency differs from the settlement currency (e.g., charging in USD but displaying the equivalent in CAD). Stored and returned as-is — no cross-validation is performed against the authoritative `amount` and `asset`. Both `amount` and `currency` must be provided together. required: - amount - currency properties: amount: type: string description: The display amount as a decimal string (e.g., `"1.37"`). example: '1.37' currency: type: string description: >- An ISO 4217 currency code in lowercase for the display amount (e.g., `cad`, `usd`). example: cad example: amount: '1.37' currency: cad example: merchantName: Acme Store displayAmount: amount: '1.37' currency: cad PaymentSession: type: object description: >- Tracks the full lifecycle of a payment from creation through settlement. Typical flow: **Create** → **Authorize** (via payment method) → **Capture**. Optional: **Void** to release uncaptured funds, or **Refund** to return captured funds. properties: paymentSessionId: allOf: - $ref: '#/components/schemas/PaymentSessionId' description: The unique identifier of the payment session. example: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: type: string description: The ID of the entity that owns the payment session. example: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 amount: type: string description: >- A decimal representation of the payment amount, denominated in `asset`. example: '1.00' asset: allOf: - $ref: '#/components/schemas/Asset' description: The symbol of the asset for the payment amount. example: usdc target: allOf: - $ref: '#/components/schemas/PaymentSessionTarget' description: The target of the payment session. example: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: type: boolean description: >- When true, a capture is automatically created after a successful authorization. When false or omitted, the merchant must create captures manually via the captures endpoint. default: false example: false expiries: $ref: '#/components/schemas/PaymentExpiries' source: allOf: - $ref: '#/components/schemas/PaymentSessionSource' description: >- The source of the payment session. Set after a successful authorization. Not present before authorization. example: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc status: allOf: - $ref: '#/components/schemas/PaymentSessionStatus' description: The most recent meaningful event on the payment session. example: created balances: $ref: '#/components/schemas/PaymentSessionBalances' authorizations: type: array description: The authorizations for this payment session. items: $ref: '#/components/schemas/Authorization' captures: type: array description: The captures for this payment session. items: $ref: '#/components/schemas/Capture' voids: type: array description: The voids for this payment session. items: $ref: '#/components/schemas/Void' refunds: type: array description: The refunds for this payment session. items: $ref: '#/components/schemas/Refund' url: allOf: - $ref: '#/components/schemas/Url' readOnly: true description: >- A URL to the hosted payment page where the payer can complete this payment session. example: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad x402Url: allOf: - $ref: '#/components/schemas/Url' readOnly: true description: >- URL for the hosted x402 payment flow. This endpoint expects an HTTP **POST** request (for example, submitting the x402 payment via request headers); do not treat it as a page opened with GET alone. Only present when the payment target supports a wallet source. example: >- https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402 redirect: $ref: '#/components/schemas/PaymentRedirect' customerDisplay: $ref: '#/components/schemas/CustomerDisplay' metadata: $ref: '#/components/schemas/Metadata' externalReferenceId: type: string maxLength: 256 description: >- An arbitrary client-supplied identifier for the payment session, such as an order ID or invoice number from the caller's own system. Not interpreted by CDP — stored and returned as-is. example: merchant-order-abc123 cancellationReason: type: string description: >- The reason the payment session was canceled. Only present when the session has been canceled. example: Customer requested cancellation. createdAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the payment session was created. example: '2025-06-15T12:00:00.000Z' updatedAt: type: string format: date-time description: >- The UTC ISO 8601 timestamp at which the payment session was last updated. example: '2025-06-15T12:05:00.000Z' example: paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114 amount: '1.00' asset: usdc target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base autoCapture: false expiries: authorizationExpiresAt: '2025-12-31T23:59:59.000Z' captureExpiresAt: '2026-01-15T23:59:59.000Z' refundExpiresAt: '2026-02-15T23:59:59.000Z' status: created balances: capturable: '0' captured: '0' refundable: '0' refunded: '0' url: >- https://pay.coinbase.com/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad x402Url: >- https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/authorizations/x402 redirect: failureUrl: https://merchant.example.com/payment/failed successUrl: https://merchant.example.com/payment/success customerDisplay: merchantName: Acme Store amount: '1.37' asset: cad externalReferenceId: merchant-order-abc123 metadata: customer_id: cust_12345 order_reference: order-67890 createdAt: '2025-06-15T12:00:00.000Z' updatedAt: '2025-06-15T12:05:00.000Z' CreatePaymentSessionRequest: type: object description: A request to create a new payment session. properties: amount: type: string description: >- A decimal representation of the payment amount, denominated in `asset`. example: '1.00' asset: allOf: - $ref: '#/components/schemas/Asset' description: The symbol of the asset for the payment amount. example: usdc target: allOf: - $ref: '#/components/schemas/PaymentSessionTarget' description: The target of the payment session. example: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base expiries: $ref: '#/components/schemas/PaymentExpiries' redirect: $ref: '#/components/schemas/PaymentRedirect' autoCapture: type: boolean description: >- When true, a capture is automatically created after a successful authorization. When false or omitted, the merchant must create captures manually via the captures endpoint. default: false example: false externalReferenceId: type: string maxLength: 256 description: >- An arbitrary client-supplied identifier for the payment session, such as an order ID or invoice number from the caller's own system. Not interpreted by CDP — stored and returned as-is. example: merchant-order-abc123 customerDisplay: $ref: '#/components/schemas/CustomerDisplay' metadata: $ref: '#/components/schemas/Metadata' required: - amount - asset - target CancelPaymentSessionRequest: type: object description: A request to cancel a payment session. properties: cancellationReason: type: string description: The reason for cancelling the payment session. example: Customer requested cancellation. EIP712Domain: type: object description: The domain of the EIP-712 typed data. properties: name: type: string description: The name of the DApp or protocol. example: Permit2 version: type: string description: The version of the DApp or protocol. example: '1' chainId: type: integer format: int64 description: The chain ID of the EVM network. example: 1 verifyingContract: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: The 0x-prefixed EVM address of the verifying smart contract. example: '0x000000000022D473030F116dDEE9F6B43aC78BA3' salt: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: The optional 32-byte 0x-prefixed hex salt for domain separation. example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' example: name: Permit2 chainId: 1 verifyingContract: '0x000000000022D473030F116dDEE9F6B43aC78BA3' EIP712Types: type: object description: > A mapping of struct names to an array of type objects (name + type). Each key corresponds to a type name (e.g., "`EIP712Domain`", "`PermitTransferFrom`"). example: EIP712Domain: - name: name type: string - name: chainId type: uint256 - name: verifyingContract type: address PermitTransferFrom: - name: permitted type: TokenPermissions - name: spender type: address - name: nonce type: uint256 - name: deadline type: uint256 TokenPermissions: - name: token type: address - name: amount type: uint256 EIP712Message: type: object description: The message to sign using EIP-712. properties: domain: $ref: '#/components/schemas/EIP712Domain' types: $ref: '#/components/schemas/EIP712Types' primaryType: type: string description: >- The primary type of the message. This is the name of the struct in the `types` object that is the root of the message. example: PermitTransferFrom message: type: object description: >- The message to sign. The structure of this message must match the `primaryType` struct in the `types` object. example: permitted: token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' amount: '1000000' spender: '0x1111111254EEB25477B68fb85Ed929f73A960582' nonce: '0' deadline: '1716239020' required: - domain - types - primaryType - message example: domain: name: Permit2 chainId: 1 verifyingContract: '0x000000000022D473030F116dDEE9F6B43aC78BA3' types: EIP712Domain: - name: name type: string - name: chainId type: uint256 - name: verifyingContract type: address PermitTransferFrom: - name: permitted type: TokenPermissions - name: spender type: address - name: nonce type: uint256 - name: deadline type: uint256 TokenPermissions: - name: token type: address - name: amount type: uint256 primaryType: PermitTransferFrom message: permitted: token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' amount: '1000000' spender: '0xFfFfFfFFfFFfFFfFFfFFFFFffFFFffffFfFFFfFf' nonce: '123456' deadline: '1717123200' EIP3009Payload: type: object title: EIP-3009 Payload description: >- An EIP-3009 TransferWithAuthorization typed-data payload. The payer must pass `data` to `eth_signTypedData_v4` and return the resulting signature. properties: payloadId: type: string description: The unique identifier of the payload. example: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: type: string description: The payload type. enum: - eip3009 example: eip3009 data: allOf: - $ref: '#/components/schemas/EIP712Message' description: >- EIP-712 typed data for a TransferWithAuthorization. Pass to `eth_signTypedData_v4`. example: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x1111111111111111111111111111111111111111' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x8f5c2d6f4b9a1e3c7d2f8a6b5c4e3d2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d required: - payloadId - type - data example: payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x1111111111111111111111111111111111111111' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: '0x8f5c2d6f4b9a1e3c7d2f8a6b5c4e3d2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d' Permit2Payload: type: object title: Permit2 Payload description: >- A Permit2 PermitTransferFrom typed-data payload. The payer must pass `data` to `eth_signTypedData_v4` and return the resulting signature. properties: payloadId: type: string description: The unique identifier of the payload. example: payload_cg4059d2-b068-6ih9-dha1-eee44f157336 type: type: string description: The payload type. enum: - permit2 example: permit2 data: allOf: - $ref: '#/components/schemas/EIP712Message' description: >- EIP-712 typed data for a Permit2 PermitTransferFrom. Pass to `eth_signTypedData_v4`. example: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address PermitTransferFrom: - name: permitted type: TokenPermissions - name: spender type: address - name: nonce type: uint256 - name: deadline type: uint256 TokenPermissions: - name: token type: address - name: amount type: uint256 primaryType: PermitTransferFrom domain: name: Permit2 chainId: 1 verifyingContract: '0x000000000022D473030F116dDEE9F6B43aC78BA3' message: permitted: token: '0xdAC17F958D2ee523a2206206994597C13D831ec7' amount: '1000000' spender: '0x3333333333333333333333333333333333333333' nonce: '0' deadline: '1767225600' required: - payloadId - type - data example: payloadId: payload_cg4059d2-b068-6ih9-dha1-eee44f157336 type: permit2 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address PermitTransferFrom: - name: permitted type: TokenPermissions - name: spender type: address - name: nonce type: uint256 - name: deadline type: uint256 TokenPermissions: - name: token type: address - name: amount type: uint256 primaryType: PermitTransferFrom domain: name: Permit2 chainId: 1 verifyingContract: '0x000000000022D473030F116dDEE9F6B43aC78BA3' message: permitted: token: '0xdAC17F958D2ee523a2206206994597C13D831ec7' amount: '1000000' spender: '0x3333333333333333333333333333333333333333' nonce: '0' deadline: '1767225600' Erc20ApprovalPayload: type: object title: ERC-20 Approval Payload description: >- An ERC-20 approval transaction payload. The payer must send `data` as an EVM transaction via `eth_sendTransaction` and return the resulting transaction hash. properties: payloadId: type: string description: The unique identifier of the payload. example: payload_bf3948c1-a957-5gh8-cgf0-ddd33e046225 type: type: string description: The payload type. enum: - erc20_approval example: erc20_approval data: type: object description: An EVM transaction object. Send via `eth_sendTransaction`. properties: chainId: type: integer description: The EVM chain ID for the transaction. example: 1 to: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: The 0x-prefixed address of the ERC-20 token contract to approve. example: '0xdAC17F958D2ee523a2206206994597C13D831ec7' data: type: string description: The ABI-encoded `approve()` calldata. example: >- 0x095ea7b3000000000000000000000000000000000022d473030f116ddee9f6b43ac78ba3000000000000000000000000ffffffffffffffffffffffffffffffffffffffff value: type: string description: The native token value to send (always `"0"` for approvals). example: '0' gas: type: string description: The estimated gas limit for the transaction. example: '63804' maxFeePerGas: type: string description: The maximum fee per gas unit (EIP-1559). example: '1751588354' maxPriorityFeePerGas: type: string description: The maximum priority fee per gas unit (EIP-1559). example: '1000000000' required: - chainId - to - data - value example: chainId: 1 to: '0xdAC17F958D2ee523a2206206994597C13D831ec7' data: >- 0x095ea7b3000000000000000000000000000000000022d473030f116ddee9f6b43ac78ba3000000000000000000000000ffffffffffffffffffffffffffffffffffffffff value: '0' gas: '63804' maxFeePerGas: '1751588354' maxPriorityFeePerGas: '1000000000' required: - payloadId - type - data example: payloadId: payload_bf3948c1-a957-5gh8-cgf0-ddd33e046225 type: erc20_approval data: chainId: 1 to: '0xdAC17F958D2ee523a2206206994597C13D831ec7' data: >- 0x095ea7b3000000000000000000000000000000000022d473030f116ddee9f6b43ac78ba3000000000000000000000000ffffffffffffffffffffffffffffffffffffffff value: '0' gas: '63804' maxFeePerGas: '1751588354' maxPriorityFeePerGas: '1000000000' SpendPermissionPayload: type: object title: Spend Permission Payload description: >- A spend permission EIP-712 typed-data payload. The payer must pass `data` to `eth_signTypedData_v4` and return the resulting signature. This grants a spender the ability to transfer tokens from the payer's smart account under the specified constraints (allowance, period, expiry). properties: payloadId: type: string description: The unique identifier of the payload. example: payload_dh5170e3-c179-7jk0-eib2-fff55g268447 type: type: string description: The payload type. enum: - spend_permission example: spend_permission data: allOf: - $ref: '#/components/schemas/EIP712Message' description: >- EIP-712 typed data for a SpendPermission approval. Pass to `eth_signTypedData_v4`. example: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address SpendPermission: - name: account type: address - name: spender type: address - name: token type: address - name: allowance type: uint160 - name: period type: uint48 - name: start type: uint48 - name: end type: uint48 - name: salt type: uint256 - name: extraData type: bytes primaryType: SpendPermission domain: name: Spend Permission Manager version: '1' chainId: 8453 verifyingContract: '0xf85210b21cc50302f477ba56686d2019dc9b67ad' message: account: '0xd53Ee96438383Bb1eff07958D110B81363E9Ab47' spender: '0x9Fb909eA400c2b8D99Be292DADf07e63B814527c' token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' allowance: '1000000000000000000' period: '86400' start: '0' end: '281474976710655' salt: '0' extraData: 0x required: - payloadId - type - data example: payloadId: payload_dh5170e3-c179-7jk0-eib2-fff55g268447 type: spend_permission data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address SpendPermission: - name: account type: address - name: spender type: address - name: token type: address - name: allowance type: uint160 - name: period type: uint48 - name: start type: uint48 - name: end type: uint48 - name: salt type: uint256 - name: extraData type: bytes primaryType: SpendPermission domain: name: Spend Permission Manager version: '1' chainId: 8453 verifyingContract: '0xf85210b21cc50302f477ba56686d2019dc9b67ad' message: account: '0xd53Ee96438383Bb1eff07958D110B81363E9Ab47' spender: '0x9Fb909eA400c2b8D99Be292DADf07e63B814527c' token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' allowance: '1000000000000000000' period: '86400' start: '0' end: '281474976710655' salt: '0' extraData: 0x OnchainSignaturePayload: description: >- A single onchain payload the payer must process to complete an onchain payment option. Inspect `type` to determine how to handle the `data` field: - `eip3009` — pass `data` to `eth_signTypedData_v4`, return the signature. - `permit2` — pass `data` to `eth_signTypedData_v4`, return the signature. - `erc20_approval` — send `data` via `eth_sendTransaction`, return the transaction hash. - `spend_permission` — pass `data` to `eth_signTypedData_v4`, return the signature. oneOf: - $ref: '#/components/schemas/EIP3009Payload' - $ref: '#/components/schemas/Permit2Payload' - $ref: '#/components/schemas/Erc20ApprovalPayload' - $ref: '#/components/schemas/SpendPermissionPayload' WalletAuthorizationOption: type: object title: Wallet Authorization Option description: >- An authorization option for completing payment via a wallet. Specifies the currency, amount, and network the payer would pay on, and the payloads the payer must sign or submit. properties: optionId: type: string description: The unique identifier of the authorization option. example: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 source: allOf: - $ref: '#/components/schemas/PaymentSourceWallet' description: The source address this authorization option applies to. example: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc amount: type: string description: >- A decimal representation of the amount the payer would pay if they choose this option, denominated in `asset`. May differ from the session amount when paying in a different asset. example: '1.00' asset: allOf: - $ref: '#/components/schemas/Asset' description: The symbol of the asset the payer would pay in for this option. example: usdc network: allOf: - $ref: '#/components/schemas/PaymentSourceNetwork' description: >- The blockchain network the transaction will occur on for this option. example: base payloads: type: array description: >- The payloads the payer must sign or submit to authorize the payment via this option. items: $ref: '#/components/schemas/OnchainSignaturePayload' example: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x1111111111111111111111111111111111111111' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x8f5c2d6f4b9a1e3c7d2f8a6b5c4e3d2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d required: - optionId - source - amount - asset - network - payloads example: optionId: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc amount: '1.00' asset: usdc network: base payloads: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x1111111111111111111111111111111111111111' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x8f5c2d6f4b9a1e3c7d2f8a6b5c4e3d2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d IneligibleWalletAuthorizationAddress: type: object title: Ineligible Wallet Authorization Address description: >- A requested payer wallet address that has no eligible authorization option for this payment session, along with a machine- and human-readable reason. properties: address: allOf: - $ref: '#/components/schemas/BlockchainAddress' description: >- The requested payer wallet address that has no eligible authorization option. example: '0xDeF9876543210FeDcBa9876543210FedcBa987654' code: type: string description: >- A machine-readable code indicating why this address has no eligible authorization option. The enum is closed — any value the server returns must be listed below. Adding a new code is a deliberate, coordinated API change; clients receiving an undocumented value should treat it as a server violating the spec. enum: - insufficient_funds x-enum-descriptions: - >- The address does not hold enough of the session asset on a supported source network to cover the session amount. example: insufficient_funds message: type: string description: >- A human-readable, English-language description of why this address has no eligible authorization option. Suitable for surfacing in product UIs — does not contain personally identifiable information or internal infrastructure details. Clients that need localized strings should dispatch on `code` and provide their own translations. example: The payer does not have sufficient funds. required: - address - code - message example: address: '0xDeF9876543210FeDcBa9876543210FedcBa987654' code: insufficient_funds message: The payer does not have sufficient funds. WalletAuthorizationOptionsResponse: type: object description: >- The available wallet authorization options for a payment session. Each option describes one way the payer can authorize the payment from their wallet. Present the options to the payer and let them choose one. Requested addresses with no eligible option appear in `ineligibleAddresses` with a `code` explaining why. properties: options: type: array description: The available wallet authorization options. items: $ref: '#/components/schemas/WalletAuthorizationOption' example: - optionId: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 source: address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456' network: base asset: usdc amount: '1.00' asset: usdc network: base payloads: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x1111111111111111111111111111111111111111' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x8f5c2d6f4b9a1e3c7d2f8a6b5c4e3d2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d - optionId: opt_b2c3d4e5-f6a7-8901-bcde-f12345678901 source: address: '0xDeF9876543210FeDcBa9876543210FedcBa987654' network: base asset: usdc amount: '1.00' asset: usdc network: base payloads: - payloadId: payload_bg5160f4-c290-8li1-fjc3-ggg66h379558 type: eip3009 data: types: EIP712Domain: - name: name type: string - name: version type: string - name: chainId type: uint256 - name: verifyingContract type: address TransferWithAuthorization: - name: from type: address - name: to type: address - name: value type: uint256 - name: validAfter type: uint256 - name: validBefore type: uint256 - name: nonce type: bytes32 primaryType: TransferWithAuthorization domain: name: USD Coin version: '2' chainId: 8453 verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' message: from: '0x3333333333333333333333333333333333333333' to: '0x2222222222222222222222222222222222222222' value: '1000000' validAfter: '0' validBefore: '1767225600' nonce: >- 0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b ineligibleAddresses: type: array description: >- Requested payer addresses that have no eligible authorization option, each with a `code` explaining why. Empty when every requested address can authorize the payment. items: $ref: '#/components/schemas/IneligibleWalletAuthorizationAddress' example: [] required: - options - ineligibleAddresses OnchainSignedPayload: type: object description: >- A processed onchain payload containing the payload ID and the payer's signature or transaction hash. The `signature` value depends on the original payload `type`: - `eip3009` / `permit2` / `spend_permission` — a hex-encoded signature from `eth_signTypedData_v4`. - `erc20_approval` — a hex-encoded transaction hash from `eth_sendTransaction`. properties: payloadId: type: string description: The unique identifier of the signed payload. example: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 signature: type: string description: >- The hex-encoded output from processing the payload. For `eip3009`, `permit2`, and `spend_permission` types, this is the cryptographic signature returned by `eth_signTypedData_v4`. For `erc20_approval` types, this is the transaction hash returned by `eth_sendTransaction`. example: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab example: payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 signature: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab WalletAuthorizationRequest: type: object description: >- A request to authorize a payment session using a wallet. The payer selects one of the options returned by the wallet authorization options endpoint and submits the signed payloads. properties: optionId: type: string description: >- The identifier of the chosen authorization option. Must match an `optionId` from the wallet authorization options response. example: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 signedPayloads: type: array description: >- The processed payloads from the payer, corresponding to the payloads in the selected authorization option. items: $ref: '#/components/schemas/OnchainSignedPayload' example: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 signature: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab metadata: $ref: '#/components/schemas/Metadata' required: - optionId - signedPayloads example: optionId: opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890 signedPayloads: - payloadId: payload_af2937b0-9846-4fe7-bfe9-ccc22d935114 signature: >- 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab CoinbaseAuthorizationRequest: type: object description: >- A request to authorize a payment session using the payer's Coinbase account authenticated via OAuth. properties: metadata: $ref: '#/components/schemas/Metadata' CreateCaptureRequest: type: object description: A request to create a capture for a payment session. properties: amount: type: string description: >- A decimal representation of the amount to capture, denominated in the session's `asset`. If omitted, the full remaining capturable amount is captured. example: '1.00' finalCapture: type: boolean description: >- When `true`, this capture is treated as the final one for the authorization. Any remaining capturable balance is released back to the payer immediately after the capture settles. When `false`, the remaining capturable balance stays held and is available for subsequent partial captures (subject to `captureExpiresAt`). Has no effect if `amount` equals the full capturable balance, since no remaining balance exists to release. example: true metadata: $ref: '#/components/schemas/Metadata' required: - finalCapture CreateVoidRequest: type: object description: >- A request to create a void for a payment session. A void releases all remaining capturable funds back to the payer, including after partial refunds as long as a capturableAmount remains. properties: metadata: $ref: '#/components/schemas/Metadata' CreateRefundRequest: type: object description: A request to create a refund for a payment session. properties: source: allOf: - $ref: '#/components/schemas/RefundSource' description: >- The source from which to fund the refund. Can be a CDP account or an onchain address. example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc amount: type: string description: >- A decimal representation of the amount to refund, denominated in the session's `asset`. If omitted, the full remaining refundable amount is refunded. example: '0.50' reason: type: string description: The reason for the refund. example: Customer returned the item. metadata: $ref: '#/components/schemas/Metadata' required: - source DisbursementId: type: string pattern: ^disbursement_[a-f0-9\-]{36}$ description: The ID of the disbursement, a UUID prefixed by `disbursement_`. example: disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad DisbursementSource: oneOf: - $ref: '#/components/schemas/transfers_Account' description: >- The source from which the disbursement is funded. Currently restricted to a CDP account owned by the merchant. Modeled as a `oneOf` so additional source types (e.g. a merchant-controlled onchain wallet) can be added without a breaking change. example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc DisbursementCoinbaseTarget: type: object title: Disbursement Coinbase Target description: A Coinbase-user target for the disbursement. properties: coinbaseUserId: type: string description: The unique identifier of the recipient within Coinbase. example: coinbase_user_abc123 required: - coinbaseUserId example: coinbaseUserId: coinbase_user_abc123 DisbursementWalletTarget: type: object title: Disbursement Wallet Target description: An onchain address target for the disbursement. properties: address: allOf: - $ref: '#/components/schemas/BlockchainAddress' description: The onchain crypto address of the recipient. example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: allOf: - $ref: '#/components/schemas/Network' description: The blockchain network on which the target receives funds. example: base required: - address - network example: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base DisbursementTarget: description: >- The target of the disbursement. Can be either a Coinbase user account or an onchain blockchain address. oneOf: - $ref: '#/components/schemas/DisbursementCoinbaseTarget' - $ref: '#/components/schemas/DisbursementWalletTarget' example: coinbaseUserId: coinbase_user_abc123 Disbursement: type: object description: >- A Disbursement represents a merchant-initiated payment of funds from a CDP account they own to a Coinbase account or onchain address. Used for standalone refunds, goodwill disbursements, rebates, and other merchant-driven payouts that are not tied to a specific payment session. Disbursements are asynchronous: the resource is returned in `pending` status and transitions to `succeeded` (with associated `onchainTransactions`) or `failed` (with `error`). properties: disbursementId: allOf: - $ref: '#/components/schemas/DisbursementId' description: The unique identifier of the disbursement. example: disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: allOf: - $ref: '#/components/schemas/DisbursementSource' description: The source from which the disbursement is funded. example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: allOf: - $ref: '#/components/schemas/DisbursementTarget' description: The target receiving the disbursement. example: coinbaseUserId: coinbase_user_abc123 amount: type: string description: >- A decimal representation of the disbursemented amount, denominated in `asset`. example: '25.00' asset: allOf: - $ref: '#/components/schemas/Asset' description: The symbol of the asset for the disbursement amount. example: usdc status: allOf: - $ref: '#/components/schemas/PaymentActionStatus' description: The current status of the disbursement. example: pending reason: type: string description: Human-readable reason for the disbursement. example: Goodwill disbursement for delayed shipment. externalReferenceId: type: string maxLength: 256 description: >- An arbitrary client-supplied identifier for the disbursement, such as a ticket ID or disbursement memo from the caller's own system. Not interpreted by CDP — stored and returned as-is. example: disbursement-2026-04-1234 metadata: $ref: '#/components/schemas/Metadata' error: allOf: - $ref: '#/components/schemas/PaymentError' description: Error details, present only when the disbursement failed. example: code: insufficient_funds message: The source account does not have sufficient funds. occurredAt: '2026-04-17T17:01:00.000Z' onchainTransactions: type: array description: The onchain transactions associated with this disbursement. items: $ref: '#/components/schemas/OnchainTransaction' example: - transactionHash: >- 0xabc123def456789012345678901234567890abcdef1234567890abcdef123456 network: base createdAt: type: string format: date-time description: The UTC ISO 8601 timestamp at which the disbursement was created. example: '2026-04-17T17:00:00.000Z' updatedAt: type: string format: date-time description: >- The UTC ISO 8601 timestamp at which the disbursement was last updated. example: '2026-04-17T17:00:00.000Z' required: - disbursementId - source - target - amount - asset - status - createdAt - updatedAt example: disbursementId: disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: coinbaseUserId: coinbase_user_abc123 amount: '25.00' asset: usdc status: pending reason: Goodwill disbursement for delayed shipment. externalReferenceId: disbursement-2026-04-1234 metadata: customer_id: cust_12345 order_id: order_67890 createdAt: '2026-04-17T17:00:00.000Z' updatedAt: '2026-04-17T17:00:00.000Z' CreateDisbursementRequest: type: object description: A request to create a disbursement. properties: source: allOf: - $ref: '#/components/schemas/DisbursementSource' description: The source from which to fund the disbursement. example: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: allOf: - $ref: '#/components/schemas/DisbursementTarget' description: The target receiving the disbursement. example: coinbaseUserId: coinbase_user_abc123 amount: type: string description: >- A decimal representation of the amount to disbursement, denominated in `asset`. example: '25.00' asset: allOf: - $ref: '#/components/schemas/Asset' description: The symbol of the asset for the disbursement amount. example: usdc reason: type: string description: Human-readable reason for the disbursement. example: Goodwill disbursement for delayed shipment. externalReferenceId: type: string maxLength: 256 description: >- An arbitrary client-supplied identifier for the disbursement, such as a ticket ID or disbursement memo from the caller's own system. Not interpreted by CDP — stored and returned as-is. example: disbursement-2026-04-1234 metadata: $ref: '#/components/schemas/Metadata' required: - source - target - amount - asset example: source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: coinbaseUserId: coinbase_user_abc123 amount: '25.00' asset: usdc reason: Goodwill disbursement for delayed shipment. externalReferenceId: disbursement-2026-04-1234 metadata: customer_id: cust_12345 order_id: order_67890 Description: type: string minLength: 0 maxLength: 500 description: A human-readable description. example: A description of the resource. EventType: type: string description: | A webhook event type identifier following dot-separated format: `..` (e.g., "onchain.activity.detected"). example: onchain.activity.detected enum: [] WebhookTarget: type: object description: > Target configuration for webhook delivery. Specifies the destination URL and any custom headers to include in webhook requests. required: - url properties: url: allOf: - $ref: '#/components/schemas/Url' description: The webhook URL to deliver events to. example: https://api.example.com/webhooks headers: type: object description: Additional headers to include in webhook requests. additionalProperties: type: string example: Authorization: Bearer token123 Content-Type: application/json example: url: https://api.example.com/webhooks headers: Authorization: Bearer token123 Content-Type: application/json WebhookSubscriptionResponse: type: object description: Response containing webhook subscription details. required: - subscriptionId - eventTypes - isEnabled - secret - target - createdAt properties: createdAt: type: string format: date-time description: When the subscription was created. example: '2025-01-15T10:30:00Z' updatedAt: type: string format: date-time description: When the subscription was last updated. example: '2025-01-16T14:00:00Z' description: allOf: - $ref: '#/components/schemas/Description' description: Description of the webhook subscription. example: Subscription for token transfer events eventTypes: type: array description: > Types of events to subscribe to. Event types follow a dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created", "acceptance.payment_session.authorization_succeeded"). items: $ref: '#/components/schemas/EventType' example: - onchain.activity.detected isEnabled: type: boolean description: Whether the subscription is enabled. example: true metadata: allOf: - $ref: '#/components/schemas/Metadata' - type: object properties: secret: type: string format: uuid deprecated: true description: >- Use the root-level `secret` field instead. Maintained for backward compatibility only. example: 123e4567-e89b-12d3-a456-426614174000 description: Additional metadata for the subscription. example: secret: 123e4567-e89b-12d3-a456-426614174000 secret: type: string format: uuid description: Secret for webhook signature validation. example: 123e4567-e89b-12d3-a456-426614174000 subscriptionId: type: string format: uuid description: Unique identifier for the subscription. example: 123e4567-e89b-12d3-a456-426614174000 target: $ref: '#/components/schemas/WebhookTarget' labels: type: object description: > Multi-label filters using total overlap logic. Total overlap means the subscription only triggers when events contain ALL these key-value pairs. Present when subscription uses multi-label format. additionalProperties: type: string example: env: dev team: payments contract_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' example: subscriptionId: 123e4567-e89b-12d3-a456-426614174000 eventTypes: - onchain.activity.detected isEnabled: true labels: contract_address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' event_name: Transfer network: base-mainnet transaction_to: '0xf5042e6ffac5a625d4e7848e0b01373d8eb9e222' description: USDC Transfer events to specific address. createdAt: '2025-11-12T09:19:52.051Z' updatedAt: '2025-11-13T11:30:00.000Z' metadata: secret: a1b2c3d4-e5f6-7890-abcd-ef1234567890 secret: a1b2c3d4-e5f6-7890-abcd-ef1234567890 target: url: https://api.example.com/webhooks WebhookSubscriptionListResponse: allOf: - type: object description: Response containing a list of webhook subscriptions. required: - subscriptions properties: subscriptions: type: array description: The list of webhook subscriptions. items: $ref: '#/components/schemas/WebhookSubscriptionResponse' - $ref: '#/components/schemas/ListResponse' WebhookSubscriptionRequest: type: object description: > Request to create a new webhook subscription with support for multi-label filtering. properties: description: allOf: - $ref: '#/components/schemas/Description' description: Description of the webhook subscription. example: Subscription for token transfer events eventTypes: type: array description: > Types of events to subscribe to. Event types follow a dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created", "acceptance.payment_session.authorization_succeeded"). The subscription will only receive events matching these types AND the label filter(s). items: $ref: '#/components/schemas/EventType' example: - onchain.activity.detected isEnabled: type: boolean description: Whether the subscription is enabled. example: true target: $ref: '#/components/schemas/WebhookTarget' metadata: $ref: '#/components/schemas/Metadata' labels: type: object description: > Optional. Multi-label filters using total overlap logic. Total overlap means the subscription will only trigger when an event contains ALL the key-value pairs specified here. Additional labels on the event are allowed and will not prevent matching. Omit to receive all events for the selected event types. **Note:** Currently, labels are supported for onchain webhooks only (max 20 labels per subscription). **Allowed labels for `onchain.activity.detected`** (all in snake_case format): - `network` (required) — Blockchain network - `contract_address` — Smart contract address - `event_name` — Event name (e.g., "Transfer", "Burn") - `event_signature` — Event signature hash - `transaction_from` — Transaction sender address - `transaction_to` — Transaction recipient address - `params.*` — Any event parameter (e.g., `params.from`, `params.to`, `params.sender`, `params.tokenId`) additionalProperties: type: string examples: - network: base-mainnet contract_address: '0xcd1f9777571493aeacb7eae45cd30a226d3e612d' event_name: Burn - network: base-mainnet contract_address: '0xbac4a9428ea707c51f171ed9890c3c2fa810305d' event_name: PriceUpdated - network: base-mainnet contract_address: '0x45c6e6a47a711b14d8357d5243f46704904578e3' event_name: Deposit required: - eventTypes - isEnabled - target WebhookSubscriptionUpdateRequest: type: object description: | Request to update an existing webhook subscription. properties: description: allOf: - $ref: '#/components/schemas/Description' description: Description of the webhook subscription. example: Updated subscription for token transfer events eventTypes: type: array description: > Types of events to subscribe to. Event types follow a three-part dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created"). items: $ref: '#/components/schemas/EventType' example: - onchain.activity.detected isEnabled: type: boolean description: Whether the subscription is enabled. example: false target: $ref: '#/components/schemas/WebhookTarget' metadata: $ref: '#/components/schemas/Metadata' labels: type: object description: > Optional. Multi-label filters that trigger only when an event contains ALL of these key-value pairs. Omit to receive all events for the selected event types. **Note:** Currently, labels are supported for onchain webhooks only (max 20 labels per subscription). **Allowed labels for `onchain.activity.detected`** (all in snake_case format): - `network` (required) — Blockchain network - `contract_address` — Smart contract address - `event_name` — Event name (e.g., "Transfer", "Burn") - `event_signature` — Event signature hash - `transaction_from` — Transaction sender address - `transaction_to` — Transaction recipient address - `params.*` — Any event parameter (e.g., `params.from`, `params.to`, `params.sender`, `params.tokenId`) additionalProperties: type: string examples: - network: base-mainnet contract_address: '0xcd1f9777571493aeacb7eae45cd30a226d3e612d' event_name: Burn - network: base-mainnet contract_address: '0xbac4a9428ea707c51f171ed9890c3c2fa810305d' event_name: PriceUpdated - network: base-mainnet contract_address: '0x45c6e6a47a711b14d8357d5243f46704904578e3' event_name: Deposit required: - eventTypes - isEnabled - target WebhookEventResponseDetail: type: object description: Details of the HTTP response received from the webhook target. properties: httpCode: type: integer description: HTTP status code returned by the webhook target. example: 200 elapsedTimeMs: type: integer description: Round-trip time of the webhook delivery in milliseconds. example: 142 body: type: string description: Response body returned by the webhook target. example: ok errorName: type: string description: >- Error name if the delivery failed (e.g., timeout, connection_refused). example: timeout example: httpCode: 200 elapsedTimeMs: 142 body: ok WebhookEventResponse: type: object description: Details of a webhook event delivery attempt for a subscription. required: - eventId - eventTypeName - status - createdAt - retryCount properties: eventId: type: string description: Unique identifier for the webhook event. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 eventTypeName: type: string description: >- The type of event that was delivered (e.g., "onchain.activity.detected"). example: onchain.activity.detected status: type: string description: Current delivery status of the event. enum: - pending - processing - succeeded - failed - retrying example: succeeded createdAt: type: string format: date-time description: Timestamp when the event delivery attempt was created. example: '2025-01-15T10:30:00Z' succeededAt: type: string format: date-time description: >- Timestamp when the event was successfully delivered. Only present if status is "succeeded". example: '2025-01-15T10:30:02Z' retryCount: type: integer description: Number of delivery retry attempts so far. example: 0 response: $ref: '#/components/schemas/WebhookEventResponseDetail' example: eventId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 eventTypeName: onchain.activity.detected status: succeeded createdAt: '2025-01-15T10:30:00Z' succeededAt: '2025-01-15T10:30:02Z' retryCount: 0 response: httpCode: 200 elapsedTimeMs: 142 body: ok WebhookEventListResponse: type: object description: Response containing a list of webhook event delivery attempts. required: - events properties: events: type: array description: The list of webhook event delivery attempts. items: $ref: '#/components/schemas/WebhookEventResponse' example: events: - eventId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 eventTypeName: onchain.activity.detected status: succeeded createdAt: '2025-01-15T10:30:00Z' succeededAt: '2025-01-15T10:30:02Z' retryCount: 0 response: httpCode: 200 elapsedTimeMs: 142 body: ok PaymentMethodId: type: string pattern: ^paymentMethod_[a-f0-9\-]{36}$ description: >- The ID of the Payment Method, which is a UUID prefixed by the string `paymentMethod_`. example: paymentMethod_8e03978e-40d5-43e8-bc93-6894a57f9324 PaymentMethodBase: type: object description: Common properties shared by all payment method types. properties: paymentMethodId: $ref: '#/components/schemas/PaymentMethodId' active: type: boolean description: >- Whether the payment method is active and can be used in transfers. A payment method may be inactive due to verification requirements or entity-level restrictions. example: true createdAt: type: string format: date-time description: The timestamp when the payment method was created. example: '2024-01-15T10:30:00Z' updatedAt: type: string format: date-time description: The timestamp when the payment method was last updated. example: '2024-01-15T10:30:00Z' required: - paymentMethodId - active - createdAt - updatedAt FedwireDetails: type: object description: Details specific to Fedwire (domestic USD wire) payment methods. properties: asset: type: string description: The asset for this payment method. Always `usd` for Fedwire. example: usd bankName: type: string description: The name of the bank. example: ALLY BANK accountLast4: type: string description: The last 4 digits of the bank account number. pattern: ^[0-9]{4}$ example: '1234' routingNumber: type: string description: The ABA routing number of the bank. pattern: ^[0-9]{9}$ example: '124003116' required: - asset - bankName - accountLast4 - routingNumber example: asset: usd bankName: ALLY BANK accountLast4: '1234' routingNumber: '124003116' FedwirePaymentMethod: type: object title: FedwirePaymentMethod description: A Fedwire (domestic USD wire) payment method linked to your entity. allOf: - $ref: '#/components/schemas/PaymentMethodBase' - type: object properties: paymentRail: type: string description: The payment rail for this payment method. enum: - fedwire example: fedwire fedwire: allOf: - $ref: '#/components/schemas/FedwireDetails' description: Fedwire (domestic USD wire) details. required: - paymentRail - fedwire example: paymentMethodId: paymentMethod_8e03978e-40d5-43e8-bc93-6894a57f9324 paymentRail: fedwire active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' fedwire: asset: usd bankName: ALLY BANK accountLast4: '1234' routingNumber: '124003116' SwiftDetails: type: object description: Details specific to SWIFT (international wire) payment methods. properties: asset: type: string description: The asset for this payment method (e.g., `eur`, `gbp`). example: eur bankName: type: string description: The name of the bank. example: Deutsche Bank accountLast4: type: string description: >- The last 4 characters of the account identifier. For IBAN-based accounts (e.g., EU), this is the last 4 characters of the IBAN. For account number-based accounts (e.g., US), this is the last 4 digits of the account number. pattern: ^[A-Z0-9]{4}$ example: '5678' ibanLast4: type: string deprecated: true description: >- Deprecated: use `accountLast4` instead. The last 4 characters of the account identifier. pattern: ^[A-Z0-9]{4}$ example: '5678' bic: type: string description: The Bank Identifier Code (BIC) / SWIFT code. pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: DEUTDEFF required: - asset - bankName - accountLast4 - bic example: asset: eur bankName: Deutsche Bank accountLast4: '5678' ibanLast4: '5678' bic: DEUTDEFF SwiftPaymentMethod: type: object title: SwiftPaymentMethod description: A SWIFT (international wire) payment method linked to your entity. allOf: - $ref: '#/components/schemas/PaymentMethodBase' - type: object properties: paymentRail: type: string description: The payment rail for this payment method. enum: - swift example: swift swift: allOf: - $ref: '#/components/schemas/SwiftDetails' description: SWIFT (international wire) details. required: - paymentRail - swift example: paymentMethodId: paymentMethod_def45678-1234-5678-9abc-def012345678 paymentRail: swift active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' swift: asset: eur bankName: Deutsche Bank accountLast4: '5678' ibanLast4: '5678' bic: DEUTDEFF SepaDetails: type: object description: Details specific to SEPA (Single Euro Payments Area) payment methods. properties: asset: type: string description: The asset for this payment method. Always `eur` for SEPA. example: eur bankName: type: string description: The name of the bank. example: ING Bank ibanLast4: type: string description: The last 4 characters of the IBAN. pattern: ^[A-Z0-9]{4}$ example: '4300' bic: type: string description: The Bank Identifier Code (BIC) / SWIFT code. pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: INGBNL2A required: - asset - bankName - ibanLast4 - bic example: asset: eur bankName: ING Bank ibanLast4: '4300' bic: INGBNL2A SepaPaymentMethod: type: object title: SepaPaymentMethod description: A SEPA (Single Euro Payments Area) payment method linked to your entity. allOf: - $ref: '#/components/schemas/PaymentMethodBase' - type: object properties: paymentRail: type: string description: The payment rail for this payment method. enum: - sepa example: sepa sepa: allOf: - $ref: '#/components/schemas/SepaDetails' description: SEPA (Single Euro Payments Area) details. required: - paymentRail - sepa example: paymentMethodId: paymentMethod_abc12345-6789-0abc-def0-123456789abc paymentRail: sepa active: true createdAt: '2024-01-15T10:30:00Z' updatedAt: '2024-01-15T10:30:00Z' sepa: asset: eur bankName: ING Bank ibanLast4: '4300' bic: INGBNL2A payment-methods_PaymentMethod: description: >- A payment method linked to your entity. Payment methods represent external financial instruments that can be used as a target for transfers. The `paymentRail` field indicates which type-specific details object is present. Type-specific fields are nested under a key matching the rail name (e.g., `fedwire`, `swift`). oneOf: - $ref: '#/components/schemas/FedwirePaymentMethod' - $ref: '#/components/schemas/SwiftPaymentMethod' - $ref: '#/components/schemas/SepaPaymentMethod' discriminator: propertyName: paymentRail mapping: fedwire: '#/components/schemas/FedwirePaymentMethod' swift: '#/components/schemas/SwiftPaymentMethod' sepa: '#/components/schemas/SepaPaymentMethod' responses: IdempotencyError: description: Idempotency key conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: idempotency_error: value: errorType: idempotency_error errorMessage: >- Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key. EndpointUnavailableError: description: >- The endpoint cannot serve the request right now, either because the API is in an unintended outage (`service_unavailable` — dependency failure, deploy issue) or because an operator has intentionally disabled this specific endpoint via a kill switch (`endpoint_unavailable`). Clients should dispatch on `errorType`: `service_unavailable` is typically transient and safe to retry, while `endpoint_unavailable` may persist until an operator re-enables the endpoint. content: application/json: schema: $ref: '#/components/schemas/Error' examples: service_unavailable: summary: API-wide outage value: errorType: service_unavailable errorMessage: Service unavailable. Please try again later. endpoint_unavailable: summary: Endpoint disabled by operator value: errorType: endpoint_unavailable errorMessage: >- This endpoint is temporarily unavailable. Please try again later. UnauthorizedError: description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: value: errorType: unauthorized errorMessage: The request is not properly authenticated. InternalServerError: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_server_error: value: errorType: internal_server_error errorMessage: An internal server error occurred. Please try again later. BadGatewayError: description: Bad gateway. content: application/json: schema: $ref: '#/components/schemas/Error' examples: bad_gateway: value: errorType: bad_gateway errorMessage: Bad gateway. Please try again later. ServiceUnavailableError: description: Service unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' examples: service_unavailable: value: errorType: service_unavailable errorMessage: Service unavailable. Please try again later. PaymentRequired: description: Payment is required to complete this operation. headers: PAYMENT-REQUIRED: description: >- Base64-encoded (RFC 4648), x402-compliant, description of the networks, assets, and amounts that will be accepted for payment. schema: type: string example: >- eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS9wcmVtaXVtLWRhdGEiLCJkZXNjcmlwdGlvbiI6IkFjY2VzcyB0byBwcmVtaXVtIG1hcmtldCBkYXRhIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIn0sImFjY2VwdHMiOlt7InNjaGVtZSI6ImV4YWN0IiwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsImFtb3VudCI6IjEwMDAwIiwiYXNzZXQiOiIweDAzNkNiRDUzODQyYzU0MjY2MzRlNzkyOTU0MWVDMjMxOGYzZENGN2UiLCJwYXlUbyI6IjB4MjA5NjkzQmM2YWZjMEM1MzI4YkEzNkZhRjAzQzUxNEVGMzEyMjg3QyIsIm1heFRpbWVvdXRTZWNvbmRzIjo2MCwiZXh0cmEiOnsibmFtZSI6IlVTREMiLCJ2ZXJzaW9uIjoiMiJ9fV19 content: application/json: schema: $ref: '#/components/schemas/Error' examples: payment_required: value: errorType: payment_required errorMessage: An x402 payment is required to access the requested resource. examples: ListTransfersResponse: summary: Page containing a regular and an FX (completed) transfer value: transfers: - transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: quoted source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base asset: usdc amount: '100.00' asset: usd sourceAmount: '103.50' sourceAsset: usd targetAmount: '100.00' targetAsset: usdc exchangeRate: sourceAsset: usd targetAsset: usdc rate: '1' fees: - type: bank amount: '2.50' asset: usd - type: conversion amount: '1.00' asset: usd expiresAt: '2023-10-08T14:45:00Z' createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' metadata: invoiceId: '12345' reference: 'Payment for invoice #12345' - transferId: transfer_bf3948c1-ab57-5gf8-cde3-ddd33e046225 status: completed source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: accountId: account_bf3948c1-ab57-5gf8-cde3-ddd33e046225 asset: eur amount: '100.00' asset: usdc sourceAmount: '100.00' sourceAsset: usdc targetAmount: '85.02' targetAsset: eur exchangeRate: sourceAsset: usdc targetAsset: eur rate: '0.8502' fees: - type: conversion amount: '0.01' asset: usdc estimate: exchangeRate: sourceAsset: usdc targetAsset: eur rate: '0.85' targetAmount: '85.00' targetAsset: eur fees: - type: conversion amount: '0.01' asset: usdc estimatedAt: '2023-10-08T14:30:00Z' completedAt: '2023-10-08T14:31:05Z' createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:31:05Z' RegularTransferQuoted: summary: Regular transfer in quoted state (USD → USDC at 1:1) value: transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114 status: quoted source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usd target: address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' network: base asset: usdc amount: '100.00' asset: usd sourceAmount: '103.50' sourceAsset: usd targetAmount: '100.00' targetAsset: usdc exchangeRate: sourceAsset: usd targetAsset: usdc rate: '1' fees: - type: bank amount: '2.50' asset: usd - type: conversion amount: '1.00' asset: usd expiresAt: '2023-10-08T14:45:00Z' createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' metadata: invoiceId: '12345' reference: 'Payment for invoice #12345' FxTransferQuoted: summary: Trade-backed FX transfer in quoted state (USDC → EUR) value: transferId: transfer_bf3948c1-ab57-5gf8-cde3-ddd33e046225 status: quoted source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: accountId: account_bf3948c1-ab57-5gf8-cde3-ddd33e046225 asset: eur amount: '100.00' asset: usdc sourceAmount: '100.00' sourceAsset: usdc estimate: exchangeRate: sourceAsset: usdc targetAsset: eur rate: '0.85' targetAmount: '85.00' targetAsset: eur fees: - type: conversion amount: '0.01' asset: usdc estimatedAt: '2023-10-08T14:30:00Z' expiresAt: '2023-10-08T14:30:10Z' createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:30:00Z' FxTransferCompleted: summary: >- Trade-backed FX transfer in completed state (top-level actuals + immutable estimate snapshot) value: transferId: transfer_bf3948c1-ab57-5gf8-cde3-ddd33e046225 status: completed source: accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114 asset: usdc target: accountId: account_bf3948c1-ab57-5gf8-cde3-ddd33e046225 asset: eur amount: '100.00' asset: usdc sourceAmount: '100.00' sourceAsset: usdc targetAmount: '85.02' targetAsset: eur exchangeRate: sourceAsset: usdc targetAsset: eur rate: '0.8502' fees: - type: conversion amount: '0.01' asset: usdc estimate: exchangeRate: sourceAsset: usdc targetAsset: eur rate: '0.85' targetAmount: '85.00' targetAsset: eur fees: - type: conversion amount: '0.01' asset: usdc estimatedAt: '2023-10-08T14:30:00Z' completedAt: '2023-10-08T14:31:05Z' createdAt: '2023-10-08T14:30:00Z' updatedAt: '2023-10-08T14:31:05Z' x-tagGroups: - name: Wallets x-groups: - name: Custodial tags: - Accounts tags: - Accounts - name: Payments tags: - Deposit Destinations - Payment Methods - Transfers - Payment Acceptance (Under Development) - name: Webhooks tags: - Webhooks