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 and for their Customers. 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. Use `GET /v2/accounts/{accountId}/products` to discover the spot products available to trade for an account (valid `productId`s to pass when creating an order).
  - name: Customers
    x-audience: public
    x-slo-tier:
      tier: beta
    description: The Customers APIs enable developers to create and manage their end-user customers. Customers can be individuals or businesses and have various capabilities like sending/receiving fiat and crypto, trading, etc. Customer information includes KYC/compliance data, verification requirements, and capability management.
  - 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. By default, incoming funds are credited to your account balance (`target.accountId`); you can instead route funds directly to an external onchain address by setting `target` to an onchain address (`target.address`, `target.network`, `target.asset`, and optionally `target.destinationTag`).

      **Metadata:**
      You can attach metadata to any deposit destination you create to track the purpose or source of deposits.


      **Example (target: account balance):**
      ```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"
        }
      }
      ```
      **Example (target: onchain address):**
      ```json
      {
        "depositDestinationId": "depositDestination_123",
        "accountId": "account_456",
        "type": "crypto",
        "crypto": {
          "network": "base",
          "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
        },
        "target": {
          "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "network": "base",
          "asset": "usdc"
        },
        "status": "active",
        "metadata": {
          "customer_id": "cust_789",
          "reference": "order-12345"
        }
      }
      ```
      Use the list endpoint to retrieve all deposit destinations.

      ## Fiat Deposit Destinations

      <Warning>
      Fiat deposit destinations are currently in **private beta** and require account enablement. Contact your Coinbase representative for access. Fields and behavior may change before general availability.
      </Warning>

      Fiat deposit destinations are bank accounts provisioned on your behalf that let an account receive USD deposits over a supported payment rail (for example, ACH). Each fiat deposit destination represents a single bank account at a single banking partner and is keyed by `accountType` (for example, `us_bank`).

      **Example:**
      ```json
      {
        "depositDestinationId": "depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336",
        "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
        "type": "fiat",
        "status": "pending",
        "fiat": {
          "accountType": "us_bank",
          "currency": "usd",
          "bankName": "Citibank, N.A.",
          "beneficiaryName": "John Smith",
          "routingNumber": "987654321",
          "accountNumber": "123456789",
          "bankAddress": "399 Park Avenue, New York, NY 10022",
          "supportedRails": ["ach"]
        },
        "target": {
          "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
          "asset": "usdc"
        }
      }
      ```
      Use the create endpoint to provision a fiat deposit destination for an account.
  - name: Disbursements
    x-audience: public
    x-slo-tier:
      tier: ga
    description: Disbursements transfer captured funds from a payment session out to a designated counterparty, such as a merchant payout to a blockchain address.
  - name: End User Account Management
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The End User Account Management APIs enable developers to manage the accounts belonging to their end users. End user accounts are typically created by end users themselves when they sign in to the developer's application via the CDP Web SDK. However, developers also have the option of creating end user accounts on behalf of their end users. Critically, developers do not have the ability to sign transactions or messages on behalf of the end user; only end users can do this.

      End User Account Management APIs are accessed by the developer's servers and authenticated by the developer's CDP API key.
  - name: End User Accounts
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The End User Accounts APIs enable end users to directly create, manage, and use their accounts. They are typically accessed via the CDP Web SDK, which handles end-user authentication and Temporary Wallet Secret management on behalf of the developer. The End User Accounts APIs offer end users full control over their accounts, including the ability to sign transactions and messages, and to export their accounts' private keys.

      ## Delegated Signing

      Delegated signing allows developers to sign and send transactions on behalf of an end user without requiring the end user to be present at signing time. This is useful for background operations, automated workflows, and scenarios where the developer's server needs to act on the end user's behalf.

      To use delegated signing, the end user must first create a short-lived **delegation grant** by authenticating with their access token and Temporary Wallet Secret. The grant specifies an `expiresAt` timestamp that defines how long the developer is authorized to sign on the end user's behalf.

      Once a delegation grant is active, the developer's server can use its CDP API key to perform signing operations for that end user. The delegation middleware transparently validates that an active (non-expired, non-revoked) grant exists for the `{project, user}` pair before allowing the operation to proceed.

      **Grant lifecycle:**

        - Delegation grants are scoped to a single project and end user pair.
        - Grants are time-bounded by the `expiresAt` timestamp and are automatically cleaned up after expiration.
        - Grants can be revoked early by either the end user (using their access token and TWS) or the
          developer (using their API key), via the `RevokeDelegationForEndUser` endpoint.
        - Only one active grant can exist per `{project, user}` pair at a given time.
  - name: EVM Accounts
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The EVM Account APIs enable you to create and use accounts across blockchains that are compatible with the Ethereum Virtual Machine (EVM).

      An **account** is a private/public key pair that is used to sign transactions and messages. The private key is generated and used only in CDP's Trusted Execution Environment (TEE), and never exposed to Coinbase or the developer.

      An EVM account is identified by its **address**, which is a 0x-prefixed hexadecimal string. The same address can be used across multiple EVM networks.

      Accounts can optionally be assigned an **account name** at creation time for easier identification in subsequent API calls. EVM account names must be globally unique across all EVM accounts in the developer's CDP Project.

      ## Authentication

      The EVM Account API uses two layers of authentication to ensure the security of your accounts' private keys:

      - **CDP Secret API Key**: This key is used to authenticate all requests to the entire suite of
         REST APIs offered on Coinbase Developer Platform.
      - **Wallet Secret**: This secret is used specifically to authenticate sensitive wallet operations
        to `POST` and `DELETE` endpoints in the EVM and Solana Account APIs.


      To learn more about creating and using these keys, visit our [Authentication docs](https://docs.cdp.coinbase.com/api-reference/v2/authentication).

      <Tip>


      **Use our SDK**


      The [CDP SDK](https://github.com/coinbase/cdp-sdk) automatically authenticates requests using your CDP Secret API Key and Wallet Secret. Use the CDP SDK for a more convenient access to our APIs.


      </Tip>
  - name: EVM Smart Accounts
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The EVM Smart Account APIs enable you to create and manage Smart Account wallets across EVM-compatible blockchains.

      A **Smart Account** is an EVM account that enables enhanced functionality such as account abstraction, batched transactions, and gas sponsorship through [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337). Smart Accounts allow users to create and manage "user operations" instead of traditional EVM transactions.
      Smart Accounts are identified by their **address**, which is a 0x-prefixed hexadecimal string.
      Smart Accounts can be assigned an optional **name** at creation time for easier identification in subsequent API calls.

      A Smart Account has a single owner, which is another EVM Account which signs the Smart Account's transactions. The owner can be a CDP EVM account, or an account managed solely by the developer.
  - name: EVM Swaps
    x-audience: public
    x-slo-tier:
      tier: beta
    description: |-
      A swap refers to the act of exchanging one token for another. The EVM Swap APIs enable you to create and manage swaps. A swap process involves:

       1. A user approves token spending via smart contract.
       2. The smart contract determines the exchange rate and facilitates the swap between the two tokens.
       3. The transaction is completed atomically and the tokens are transferred to the user's wallet.

      The Swap API supports:

       - **Getting a price**: Estimate the amount of tokens you will receive for a given amount of exchanged tokens.
       - **Creating a swap quote**: Return a swap transaction payload that you can use to sign and submit in order to execute the swap.

      For the easiest experience creating, signing, and submitting a swap, we recommend using the [CDP SDK](https://github.com/coinbase/cdp-sdk/).
      - [Python SDK examples](https://github.com/coinbase/cdp-sdk/tree/main/python#evm-swaps)
      - [TypeScript SDK examples](https://github.com/coinbase/cdp-sdk/tree/main/typescript#evm-swaps)

      To read more about using the EVM Swap APIs, please see our [Swap API docs](https://docs.cdp.coinbase.com/swaps/docs/welcome).
  - name: EVM Token Balances
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The EVM Token Balances APIs enable you to retrieve the balances of EVM addresses.
      This includes tokens (i.e. ERC-20s) and the native gas token of the network.
      ## Denomination
      - 'amount' is denominated in the smallest indivisible unit of the token. For ETH, the smallest indivisible unit is Wei (10^-18 ETH). For ERC-20s, the smallest unit is the unit returned from `function totalSupply() public view returns (uint256)`.
      - 'decimals' is the exponential value N that satisfies the equation `amount * 10^-N = standard_denomination`. The standard denomination is the most commonly used denomination for the token.

        - In the case of the native gas token, `decimals` is defined via convention. As an example, for ETH of Ethereum mainnet, the standard denomination is 10^-18 the smallest denomination (Wei). As such, for ETH on Ethereum mainnet, `decimals` is 18.
        - In the case of ERC-20 tokens, `decimals` is defined via configuration. `decimals` will be the number returned by `function decimals() public view returns (uint8)` on the underlying token contract.
  - name: Faucets
    x-audience: public
    x-slo-tier:
      tier: ga
    description: The Faucet APIs enable you to request funds on supported test networks. Faucets are for testing purposes and make development easier by providing a source of funds.
  - name: Onchain Data
    x-audience: public
    x-slo-tier:
      tier: ga
    description: Query and analyze blockchain data with high performance and reliability. Features include real-time token balances, token discovery, and transaction history with freshness, accuracy, and completeness like never before.
  - name: Onramp
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The v2 Onramp APIs are an evolution of our [v1 APIs](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/), designed to make the fiat-to-crypto experience feel native to your applications for higher conversion and less friction. These APIs only cover a subset of Coinbase Onramp functionality as described below, for all other use cases please refer to our [v1 APIs](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/).

      ## Supported Use Cases

      #### Guest Checkout Onramp (Apple Pay & Google Pay)

      This use case allows you to offer an Apple Pay or Google Pay onramp experience with debit cards in your app without users needing to create or log into a Coinbase account. Our API returns a `paymentLink` URL that renders an Apple Pay or Google Pay button for you to load in a webview or iframe in your app, making the onramp experience feel native to your application.

      Refer to our [detailed integration guide](https://docs.cdp.coinbase.com/onramp/headless-onramp/overview) for more information on the limitations and requirements of this use case. See our [onramp mobile demo app](https://github.com/coinbase/onramp-demo-mobile) for a reference implementation.

      #### Hosted UI Onramp

      This use case enables you to offer a full-featured onramp experience by redirecting users to a Coinbase-hosted page where they can choose to log into their existing Coinbase account or proceed as a guest. The Onramp Session API generates secure, single-use Onramp URLs with customizable parameters, allowing you to control available payment methods, preset transaction amounts, and cryptocurrencies for a tailored user experience.

      Refer to our [guide](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/generating-onramp-url) for implementation details and customization options for this use case.
  - 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: Payment Sessions
    x-audience: public
    x-slo-tier:
      tier: ga
    description: Payment Sessions track the full lifecycle of a merchant payment — from authorization through capture, void, or refund. Each session records every operation and balance change across its lifecycle.
  - name: Policy Engine
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The Policy Engine APIs evaluate policies (a set of rules) to govern the behavior of accounts or projects, such as enforce allowlists and denylists.
      - A **policy** is a collection of `rules` with defined criteria.
      - Each **rule** contains a specified `action`, `operation`, and `criteria`:
        - An `action` can either `accept` or `reject` a transaction if the criteria in the rule are met.
        - `criteria` is an array of logical expressions. All parameters must evaluate to true for the action to be applied.
        - An `operation` corresponds to a CDP v2 API:
            - `signEvmTransaction` or `signSolTransaction` for signing transactions (to set a transaction limit).
            - `sendEvmTransaction` for signing a transaction, and sending it to a supported network.
            - `signEvmHash` for signing an arbitrary 32 byte hash.
            - `signEvmMessage` for signing an [EIP-191](https://eips.ethereum.org/EIPS/eip-191) message.
            - `prepareUserOperation` for preparing user operations on a smart account.
            - `sendUserOperation` for sending user operations using a smart account.
            - `signEndUserEvmTransaction` or `signEndUserSolTransaction` for signing end user transactions (to set a transaction limit).
            - `sendEndUserEvmTransaction` for signing an end user transaction, and sending it to a supported EVM network.
            - `sendEndUserSolTransaction` for signing an end user transaction, and sending it to a supported Solana network.
            - `signEndUserEvmMessage` for signing an end user [EIP-191](https://eips.ethereum.org/EIPS/eip-191) message.
            - `signEndUserEvmTypedData` for signing end user [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data.
            - `signEndUserSolMessage` for signing an end user Solana message.
      - A **rule** indicates how an operation should behave, specifying whether a request with defined criteria should be accepted or rejected.
      ## Policy Scope
      Policies can be applied at the project and/or account level:
      - **Project-level policy**: A `project`-level policy applies to all accounts in a CDP Project. Only one project-level policy can be applied to accounts within a CDP Project at any given time.
      - **Account-level policy**: An `account`-level policy applies to one or more accounts. An account
        can have at most one account-level policy at any given time.

      Thus, a single account can be assigned at most two policies at any given time: one project-level policy and one account-level policy.

      **Note:** End user operation rules (e.g., `signEndUserEvmTransaction`, `sendEndUserSolTransaction`) currently only apply for policies with the `project` scope.

      Scope is specified in the `scope` field of a policy:
      ```json {
        "description": "Project-level policy",
        "scope": "account",
        ...
      ```
      ## Policy Evaluation
      **Project-level policies** are evaluated first, followed by **account-level policies**.
      The Policy Engine will process the request against each rule in the order it is defined within the `rules` array:

        1. If the rule's `criteria` (processed as a logical **AND** operation applied to a list of independently evaluated boolean expressions) are met, `accept` or `reject` behavior is applied immediately and the engine stops further evaluation of the policy.
        1. If after policy evaluation, no rule's `criteria` are met, the engine moves to processing the next policy (i.e., an `account`-level policy).
        1. If no further policies exist, the request is rejected.

      For example, the following policy is a project-level policy with two rules. The Policy Engine will:

         1. **Evaluate the first rule:** For a `signEvmTransaction` request, accept the request if the transaction is less than or equal to 1000000000000000000 wei OR
         1. **Evaluate the second rule:** if the request is a `signEvmTransaction` request, accept the request if the transaction is less than or equal to 2000000000000000000 wei AND the request is made to the address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`.
         1. **If the request does not meet the criteria of either rule**, the engine will move on to evaluate an `account`-level policy (if one exists).
         1. Otherwise, the request is rejected.

      Rules are processed in the order they are defined. Once a rule applies to an operation, subsequent rules are ignored.
      ```json
      {
        "description": "Project-level policy",
        "scope": "project",
        "rules": [
          {
            "action": "accept",
            "operation": "signEvmTransaction",
            "criteria": [
              {
                "type": "ethValue",
                "ethValue": "1000000000000000000",
                "operator": "<="
              }
            ]
          },
          {
            "action": "accept",
            "operation": "signEvmTransaction",
            "criteria": [
              {
                "type": "ethValue",
                "ethValue": "2000000000000000000",
                "operator": "<="
              },
              {
                "type": "evmAddress",
                "addresses": [
                  "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
                ],
                "operator": "in"
              }
            ]
          }
        ]
      }
      ```

      ## Policy Application

      Project-level policies are applied to all accounts in a CDP Project. They will apply retroactively even if the project-level policy is created after the account was created. To disable a project-level policy, you must remove the project-level policy from the CDP Project using the `deletePolicy` operation.

      Account-level policies can be applied in two ways:
      - By specifying the `accountPolicy` field in the request body of the `createEvmAccount` and
        `createSolAccount` operations.

      - By specifying the `accountPolicy` field in the request body of the `updateEvmAccount` and
        `updateSolanaAccount` operations.


      ## Criteria

      The following criteria are supported:

      ### SignEvmTransaction Criteria
      #### ethValue
      A criterion based on the value of the transaction. The transaction's `value` field is compared to the criterion's `ethValue` field using the `operator` field.
      #### evmAddress
      A criterion based on the recipient address of the transaction. The transaction's `to` field is compared to the criterion's `addresses` field using the `operator` field.
      #### evmData
      A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; `string`, `bool`, `uint(8,16,32,64,256)`, `int(8,16,32,64,256)`, `address`, and both fixed and dynamic length `bytes`.
      #### netUSDChange
      A criterion based on the USD denominated market value of assets being transferred, or exposing the sender to. The types of assets included in the calculation include native assets, `ERC20`, `ERC721`, and `ERC1155` tokens. The sum total USD amount of assets being transferred and exposed is compared to the criterion's `changeCents` field using the `operator` field. If signing a testnet transaction, then this criterion configuration will be ignored.
      ### SendEvmTransaction Criteria
      #### ethValue
      A criterion based on the value of the transaction. The transaction's `value` field is compared to the criterion's `ethValue` field using the `operator` field.
      #### evmAddress
      A criterion based on the recipient address of the transaction. The transaction's `to` field is compared to the criterion's `addresses` field using the `operator` field.
      #### evmNetwork
      A criterion based on the intended network of the transaction. The `network` field in the `sendEvmTransaction` request body is compared to the criterion's `networks` field using the `operator` field.
      Valid networks for this criterion include:
        - `base`
        - `base-sepolia`
        - `ethereum`
        - `ethereum-sepolia`
        - `avalanche`
        - `polygon`
        - `optimism`
        - `arbitrum`
        - `arbitrum-sepolia`
        - `world`
        - `world-sepolia`

      #### evmData
      A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; `string`, `bool`, `uint(8,16,32,64,256)`, `int(8,16,32,64,256)`, `address`, and both fixed and dynamic length `bytes`.
      #### netUSDChange
      A criterion based on the USD denominated market value of assets being transferred, or exposing the sender to. The types of assets included in the calculation include native assets, `ERC20`, `ERC721`, and `ERC1155` tokens. The sum total USD amount of assets being transferred and exposed is compared to the criterion's `changeCents` field using the `operator` field. If sending a testnet transaction, then this criterion configuration will be ignored.
      ### SendUserOperation Criteria
      #### ethValue
      A criterion based on the value of the user operation. The operation's `value` fields are compared to the criterion's `ethValue` field using the `operator` field.
      #### evmAddress
      A criterion based on the recipient address of the operation. The operation's `to` fields are compared to the criterion's `addresses` field using the `operator` field.
      #### evmData
      A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; `string`, `bool`, `uint(8,16,32,64,256)`, `int(8,16,32,64,256)`, `address`, and both fixed and dynamic length `bytes`.
      ### PrepareUserOperation Criteria
      #### ethValue
      A criterion based on the value of the user operation. The operation's `value` fields are compared to the criterion's `ethValue` field using the `operator` field.
      #### evmAddress
      A criterion based on the recipient address of the user operation. The operation's `to` fields are compared to the criterion's `addresses` field using the `operator` field.
      #### evmNetwork
      A criterion based on the intended network of the user operation. The `network` field in the `prepareUserOperation` request body is compared to the criterion's `networks` field using the `operator` field.
      Valid networks for this criterion include:
        - `base-sepolia`
        - `base`
        - `arbitrum`
        - `optimism`
        - `zora`
        - `polygon`
        - `bnb`
        - `avalanche`
        - `ethereum`
        - `ethereum-sepolia`

      #### evmData
      A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; `string`, `bool`, `uint(8,16,32,64,256)`, `int(8,16,32,64,256)`, `address`, and both fixed and dynamic length `bytes`.
      ### SignEvmHash Criteria
      The `signEvmHash` operation does not accept any criteria. To prevent this operation from being executed by any account, specify a rule with `signEvmHash` as the operation, and `reject` as its action.
      ### SignEvmMessage Criteria
      #### evmMessage
      A criterion based on the intended message to be signed. The `match` field in the criteria is a [RE2](https://github.com/google/re2/wiki/Syntax) compliant regular expression that will be executed against the message in the API request.
      ### SignSolMessage Criteria
      #### solMessage
      A criterion based on the intended message to be signed. The `match` field in the criteria is a [RE2](https://github.com/google/re2/wiki/Syntax) compliant regular expression that will be executed against the message in the API request.
      ### SignSolTransaction Criteria
      #### solAddress
      A criterion based on the recipient addresses of the transaction. The criterion's `address` field is compared to the list of addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solValue
      A criterion based on the value of the transaction. The criterion's `solValue` field is compared to the transaction's `value`, which is the amount of SOL in lamports being transferred, using the `operator` field.
      #### splAddress
      A criterion based on the recipient addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### splValue
      A criterion based on the SPL token value of SPL token transfer instructions in the transaction. The criterion's `splValue` field is compared to the transaction instruction's `value` field, which is the amount of the SPL token being transferred, using the `operator` field.
      #### mintAddress
      A criterion based on the token mint addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solData
      A criterion based on Solana transaction instruction data. The criterion uses Interface Definition Language (IDL) specifications to decode and validate instruction data against specific rules. The `idls` field specifies which Solana programs to validate against (either known program names like "SystemProgram" and "TokenProgram", or custom IDL objects), and the `conditions` field defines instruction-specific validation rules including instruction names and parameter constraints.
      #### programId
      A criterion based on the program IDs of a transaction's instructions. The criterion's `programIds` field is compared to the list of program IDs in the transaction's instructions using the `operator` field.
      ### SendSolTransaction Criteria
      #### solAddress
      A criterion based on the recipient addresses of the transaction. The criterion's `address` field is compared to the list of addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solValue
      A criterion based on the value of the transaction. The criterion's `solValue` field is compared to the transaction's `value`, which is the amount of SOL in lamports being transferred, using the `operator` field.
      #### splAddress
      A criterion based on the recipient addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### splValue
      A criterion based on the SPL token value of SPL token transfer instructions in the transaction. The criterion's `splValue` field is compared to the transaction instruction's `value` field, which is the amount of the SPL token being transferred, using the `operator` field.
      #### mintAddress
      A criterion based on the token mint addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solData
      A criterion based on Solana transaction instruction data. The criterion uses Interface Definition Language (IDL) specifications to decode and validate instruction data against specific rules. The `idls` field specifies which Solana programs to validate against (either known program names like "SystemProgram" and "TokenProgram", or custom IDL objects), and the `conditions` field defines instruction-specific validation rules including instruction names and parameter constraints.
      #### programId
      A criterion based on the program IDs of a transaction's instructions. The criterion's `programIds` field is compared to the list of program IDs in the transaction's instructions using the `operator` field.
      #### solNetwork
      A criterion based on the intended network of the transaction. The `network` field in the `sendSolanaTransaction` request body is compared to the criterion's `networks` field using the `operator` field.
      Valid networks for this criterion include:
        - `solana-devnet`
        - `solana`

      ## End User Criteria for User Wallets
      End user criteria apply to operations performed by end users via user wallets. These criteria are only evaluated for policies with the `project` scope. The supported criterion types for each end user operation mirror their non-end-user counterparts.
      ### SignEndUserEvmTransaction Criteria
      #### ethValue
      A criterion based on the value of the transaction. The transaction's `value` field is compared to the criterion's `ethValue` field using the `operator` field.
      #### evmAddress
      A criterion based on the recipient address of the transaction. The transaction's `to` field is compared to the criterion's `addresses` field using the `operator` field.
      #### evmData
      A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; `string`, `bool`, `uint(8,16,32,64,256)`, `int(8,16,32,64,256)`, `address`, and both fixed and dynamic length `bytes`.
      #### netUSDChange
      A criterion based on the USD denominated market value of assets being transferred, or exposing the sender to. The types of assets included in the calculation include native assets, `ERC20`, `ERC721`, and `ERC1155` tokens. The sum total USD amount of assets being transferred and exposed is compared to the criterion's `changeCents` field using the `operator` field. If signing a testnet transaction, then this criterion configuration will be ignored.
      ### SendEndUserEvmTransaction Criteria
      #### ethValue
      A criterion based on the value of the transaction. The transaction's `value` field is compared to the criterion's `ethValue` field using the `operator` field.
      #### evmAddress
      A criterion based on the recipient address of the transaction. The transaction's `to` field is compared to the criterion's `addresses` field using the `operator` field.
      #### evmNetwork
      A criterion based on the intended network of the transaction. The `network` field in the `sendEndUserEvmTransaction` request body is compared to the criterion's `networks` field using the `operator` field.
      Valid networks for this criterion include:
        - `base`
        - `base-sepolia`
        - `ethereum`
        - `ethereum-sepolia`
        - `avalanche`
        - `polygon`
        - `optimism`
        - `arbitrum`

      #### evmData
      A criterion based on encoded transaction data that evaluates the function being called, as well as any number of arguments accessed by either name or index. Currently this criterion only supports primitive types; `string`, `bool`, `uint(8,16,32,64,256)`, `int(8,16,32,64,256)`, `address`, and both fixed and dynamic length `bytes`.
      #### netUSDChange
      A criterion based on the USD denominated market value of assets being transferred, or exposing the sender to. The types of assets included in the calculation include native assets, `ERC20`, `ERC721`, and `ERC1155` tokens. The sum total USD amount of assets being transferred and exposed is compared to the criterion's `changeCents` field using the `operator` field. If sending a testnet transaction, then this criterion configuration will be ignored.
      ### SignEndUserEvmMessage Criteria
      #### evmMessage
      A criterion based on the intended message to be signed. The `match` field in the criteria is a [RE2](https://github.com/google/re2/wiki/Syntax) compliant regular expression that will be executed against the message in the API request.
      ### SignEndUserEvmTypedData Criteria
      #### evmTypedDataField
      A criterion based on the fields of the [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data being signed. The `types` field specifies the EIP-712 type definitions and primary type, while the `conditions` field defines validation rules for specific fields within the typed data message. Conditions can target address fields, numerical fields, or string fields, and can reference deeply nested values using dot-separated paths.
      #### evmTypedDataVerifyingContract
      A criterion based on the verifying contract address in the [EIP-712](https://eips.ethereum.org/EIPS/eip-712) domain separator. The domain's `verifyingContract` field is compared to the criterion's `addresses` field using the `operator` field.
      ### SignEndUserSolTransaction Criteria
      #### solAddress
      A criterion based on the recipient addresses of the transaction. The criterion's `address` field is compared to the list of addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solValue
      A criterion based on the value of the transaction. The criterion's `solValue` field is compared to the transaction's `value`, which is the amount of SOL in lamports being transferred, using the `operator` field.
      #### splAddress
      A criterion based on the recipient addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### splValue
      A criterion based on the SPL token value of SPL token transfer instructions in the transaction. The criterion's `splValue` field is compared to the transaction instruction's `value` field, which is the amount of the SPL token being transferred, using the `operator` field.
      #### mintAddress
      A criterion based on the token mint addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solData
      A criterion based on Solana transaction instruction data. The criterion uses Interface Definition Language (IDL) specifications to decode and validate instruction data against specific rules. The `idls` field specifies which Solana programs to validate against (either known program names like "SystemProgram" and "TokenProgram", or custom IDL objects), and the `conditions` field defines instruction-specific validation rules including instruction names and parameter constraints.
      #### programId
      A criterion based on the program IDs of a transaction's instructions. The criterion's `programIds` field is compared to the list of program IDs in the transaction's instructions using the `operator` field.
      ### SendEndUserSolTransaction Criteria
      #### solAddress
      A criterion based on the recipient addresses of the transaction. The criterion's `address` field is compared to the list of addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solValue
      A criterion based on the value of the transaction. The criterion's `solValue` field is compared to the transaction's `value`, which is the amount of SOL in lamports being transferred, using the `operator` field.
      #### splAddress
      A criterion based on the recipient addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### splValue
      A criterion based on the SPL token value of SPL token transfer instructions in the transaction. The criterion's `splValue` field is compared to the transaction instruction's `value` field, which is the amount of the SPL token being transferred, using the `operator` field.
      #### mintAddress
      A criterion based on the token mint addresses of SPL token transfer instructions in the transaction. The criterion's `addresses` field is compared to the list of token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array using the `operator` field.
      #### solData
      A criterion based on Solana transaction instruction data. The criterion uses Interface Definition Language (IDL) specifications to decode and validate instruction data against specific rules. The `idls` field specifies which Solana programs to validate against (either known program names like "SystemProgram" and "TokenProgram", or custom IDL objects), and the `conditions` field defines instruction-specific validation rules including instruction names and parameter constraints.
      #### programId
      A criterion based on the program IDs of a transaction's instructions. The criterion's `programIds` field is compared to the list of program IDs in the transaction's instructions using the `operator` field.
      #### solNetwork
      A criterion based on the intended network of the transaction. The `network` field in the `sendEndUserSolTransaction` request body is compared to the criterion's `networks` field using the `operator` field.
      Valid networks for this criterion include:
        - `solana-devnet`
        - `solana`

      ### SignEndUserSolMessage Criteria
      #### solMessage
      A criterion based on the intended message to be signed. The `match` field in the criteria is a [RE2](https://github.com/google/re2/wiki/Syntax) compliant regular expression that will be executed against the message in the API request.
      ## Restricting Contract Interactions on Ethereum
      Smart contract function restrictions serve as a critical security and governance mechanism in decentralized applications, allowing developers and organizations to implement fine-grained access controls over their protocol interactions.
      One of the primary use cases for function restrictions is protecting high-risk operations from unauthorized access such as:
      - Fund transfers - Contract upgrades - Parameter modifications - Emergency pauses
      Policy Engine supports such restrictions that evaluate against transaction data with the `evmData` criterion for the `signEvmTransaction`, and `sendEvmTransaction` operations.
      ## Examples
      ### USD Limits
      The following example demonstrates a policy that only allows transactions to transfer, or expose the sender to, less than $100.00 worth of assets at a time. This USD denominated amount includes native assets, `ERC20`, `ERC721`, and `ERC1155` tokens calculated using current market prices.
      ```json {
        "scope": "account",
        "description": "Reject assets out over 100 USD",
        "rules": [
          {
            "action": "reject",
            "operation": "sendEvmTransaction",
            "criteria": [
              {
                "type": "netUSDChange",
                "changeCents": 10000,
                "operator": ">",
              },
            ],
          },
          {
            "action": "reject",
            "operation": "signEvmTransaction",
            "criteria": [
              {
                "type": "netUSDChange",
                "changeCents": 10000,
                "operator": ">",
              },
            ],
          },
        ],
      } ```
      ### Limiting USDC Spend
      This policy restricts USDC transactions on the Base network to transfers of 10,000 tokens or less. It applies to both signing and sending transactions to the USDC contract address, using the ERC20 ABI to validate that only `transfer` function calls with a `value` parameter under the specified limit are permitted.
      ```json {
        "description": "Limit USDC Spend",
        "scope": "account",
        "rules": [
          {
            "action": "accept",
            "operation": "sendEvmTransaction",
            "criteria": [
              {
                "type": "evmNetwork",
                "networks": ["base"],
                "operator": "in"
              },
              {
                "type": "evmAddress",
                "addresses": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
                "operator": "in"
              },
              {
                "type": "evmData",
                "abi": "erc20",
                "conditions": [
                  {
                    "function": "transfer",
                    "params": [
                      {
                        "name": "value",
                        "operator": "<=",
                        "value": "10000"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "action": "accept",
            "operation": "signEvmTransaction",
            "criteria": [
              {
                "type": "evmAddress",
                "addresses": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
                "operator": "in"
              },
              {
                "type": "evmData",
                "abi": "erc20",
                "conditions": [
                  {
                    "function": "transfer",
                    "params": [
                      {
                        "name": "value",
                        "operator": "<=",
                        "value": "10000"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      } ```.
  - name: Solana Accounts
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The Solana Account APIs enable you to create and use Solana accounts across SVM-compatible blockchains.

      An **account** is a private/public key pair that is used to sign transactions and messages. The private key is generated and used only in CDP's Trusted Execution Environment (TEE), and never exposed to Coinbase or the developer.

      A Solana account is identified by its **address**, which is a base-58 encoded string.

      Accounts can optionally be assigned an **account name** at creation time for easier identification in subsequent API calls. Solana account names must be globally unique across all Solana accounts in the developer's CDP Project.

      ## Authentication

      The Solana Account APIs use two layers of authentication to ensure the security of your accounts' private keys:

      - **CDP Secret API Key**: This key is used to authenticate all requests to the entire suite of
         REST APIs offered on Coinbase Developer Platform.
      - **Wallet Secret**: This secret is used specifically to authenticate sensitive wallet operations
        to `POST` and `DELETE` endpoints in the EVM and Solana Account APIs.


      To learn more about creating and using these keys, visit our [Authentication docs](https://docs.cdp.coinbase.com/api-reference/v2/authentication).

      <Tip>


      **Use our SDK**


      The [CDP SDK](https://github.com/coinbase/cdp-sdk) automatically authenticates requests using your CDP Secret API Key and Wallet Secret. Use the CDP SDK for a more convenient access to our APIs.


      </Tip>
  - name: Solana Token Balances
    x-audience: public
    x-slo-tier:
      tier: ga
    description: |-
      The Solana Token Balances APIs enable you to retrieve the balances of Solana addresses.
      This includes SPL tokens and the native SOL token of the network.
      ## Denomination
      - 'amount' is denominated in the smallest indivisible unit of the token. For SOL, the smallest indivisible unit is lamports (10^-9 SOL). For SPL tokens, the smallest unit is defined by the token's decimals configuration.
      - 'decimals' is the exponential value N that satisfies the equation `amount * 10^-N = standard_denomination`. The standard denomination is the most commonly used denomination for the token.

        - For native SOL, `decimals` is 9 (1 SOL = 10^9 lamports).
        - For SPL tokens, `decimals` is defined in the token's mint configuration.
  - name: SQL API
    x-audience: public
    x-slo-tier:
      tier: ga
    description: The SQL API enables you to write performant, high-freshness, and endlessly flexible SQL queries against onchain data.
  - 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: Wallet Webhooks
    x-audience: public
    x-slo-tier:
      tier: ga
    description: The `wallet.activity.*` webhook payloads describe wallet activity, transaction, delegation, and signing events emitted by CDP.
  - 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.
  - name: x402 Facilitator
    x-audience: public
    x-slo-tier:
      tier: beta
    description: |-
      The x402 payment protocol is an HTTP-based payment protocol that enables developers running resource servers to accept payments from users using a variety of payment methods.
      For more details on the x402 payment protocol, please see the [x402 specification](https://www.x402.org/).
      The x402 Facilitator APIs enable you to facilitate payments using the x402 payment protocol by exposing two APIs:
      - `POST /v2/x402/verify`: Verify a payment with a supported scheme and network.
      - `POST /v2/x402/settle`: Settle a payment with a supported scheme and network.
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: []
      x-audience: public
      x-required-permissions:
        permissions:
          - accounts:read@entity
        enforcement: any
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
        - name: owner
          in: query
          required: false
          description: |-
            Filter accounts by owner. Values can be specific Owner IDs or owner type wildcards. Multiple values can be combined as a comma-separated list.

            **Specific Owner IDs:**
            * `entity_<uuid>` - Accounts owned by a specific entity
            * `customer_<uuid>` - Accounts owned by a specific customer

            **Owner type wildcards:**
            * `entity` - All entity-owned accounts
            * `customer` - All customer-owned accounts

            **Examples:**
            * `owner=customer_af29...` - A specific customer's accounts
            * `owner=customer` - All customer accounts
            * `owner=entity,customer_af29...` - Entity accounts and a specific customer's accounts
            * When omitted, accounts with any owner are returned.
          schema:
            type: array
            items:
              type: string
              description: An owner filter value. Can be a specific Owner ID (e.g. `entity_<uuid>`, `customer_<uuid>`) or an owner type wildcard (`entity`, `customer`).
              pattern: ^(entity|customer)(_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?$
          style: form
          explode: false
          examples:
            specific_customer:
              summary: A specific customer's accounts
              value:
                - customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
            all_customers:
              summary: All customer accounts
              value:
                - customer
            entity_and_customer:
              summary: Entity accounts and a specific customer's accounts
              value:
                - entity
                - customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
            all_owners:
              summary: All accounts (entity and all customers)
              value:
                - entity
                - customer
        - 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==
                customer_owned:
                  summary: Account owned by a Customer of yours
                  value:
                    accounts:
                      - accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                        type: cdp
                        owner: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                        name: ABC XYZ Customer 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. Two ownership modes are supported:

        - **Entity-owned**: when `owner` is omitted, the account is owned by the
          Entity making the request. Returns an account with `owner: entity_<uuid>`.

        - **Customer-owned**: pass a Customer ID as `owner`
          (e.g. `customer_af2937b0-9846-4fe7-bfe9-ccc22d935114`). The Customer
          must have the `custodyCrypto`, `custodyFiat`, and `custodyStablecoin`
          capabilities enabled, otherwise the request is rejected with
          `customer_not_authorized` (HTTP 403).
      operationId: createFoundationAccount
      tags:
        - Accounts
      security:
        - apiKeyAuth: []
      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
              customer_owned:
                summary: Create an account owned by a Customer of yours
                value:
                  owner: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                  name: ABC XYZ Customer 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'
                customer_owned:
                  summary: Account owned by a Customer of yours
                  value:
                    accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    type: cdp
                    owner: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    name: ABC XYZ Customer 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
                      - custodyFiat
                      - custodyStablecoin
        '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: []
      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'
                customer_owned:
                  summary: Account owned by a Customer of yours
                  value:
                    accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    type: cdp
                    owner: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    name: ABC XYZ Customer 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: []
      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: []
      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: public
      tags:
        - Payment Sessions
      security: []
      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/customers:
    post:
      summary: Create a customer
      description: |
        Create a new customer record. You can optionally request capabilities
        and submit verification requirements in the same request.

        This endpoint supports creating a customer with:
        - Minimal data (customer type only)
        - Capability requests
        - KYC data submission
        - Combined request for capability and required info for verification
      operationId: createCustomer
      x-audience: public
      x-required-permissions:
        permissions:
          - customers:write@entity
        enforcement: any
      tags:
        - Customers
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            examples:
              createWithCapabilities:
                summary: Create customer with capability requests
                value:
                  type: individual
                  individual:
                    firstName: Jane
                    lastName: Doe
                    address:
                      line1: 500 Main St
                      city: Boston
                      state: MA
                      postCode: '02108'
                      countryCode: US
                  capabilities:
                    custodyCrypto:
                      requested: true
                    transferCrypto:
                      requested: true
              createWithTosAcceptances:
                summary: Create customer and record Terms of Service acceptance
                value:
                  type: individual
                  individual:
                    firstName: Jane
                    lastName: Doe
                    address:
                      line1: 500 Main St
                      city: Boston
                      state: MA
                      postCode: '02108'
                      countryCode: US
                  capabilities:
                    custodyCrypto:
                      requested: true
                    transferCrypto:
                      requested: true
                  tosAcceptances:
                    - versionId: us_individual_2026-05-29
                      language: en
                      acceptedAt: '2026-04-10T12:00:00Z'
              createWithTaxAttestations:
                summary: Create customer and record a tax attestation
                value:
                  type: individual
                  individual:
                    firstName: Jane
                    lastName: Doe
                    address:
                      line1: 500 Main St
                      city: Boston
                      state: MA
                      postCode: '02108'
                      countryCode: US
                  capabilities:
                    transferFiat:
                      requested: true
                  taxAttestations:
                    - form: us_w9
                      isExemptBackupWithholding: true
                      edeliveryConsent: true
                      acceptedAt: '2026-04-17T20:00:00Z'
              createMinimal:
                summary: Create customer without capabilities
                value:
                  type: individual
                  individual: {}
      responses:
        '201':
          description: Customer created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                customerId: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                type: individual
                individual: {}
                capabilities:
                  custodyCrypto:
                    requested: true
                    status: pending
                  custodyFiat:
                    requested: false
                    status: unrequested
                  custodyStablecoin:
                    requested: false
                    status: unrequested
                  tradeCrypto:
                    requested: false
                    status: unrequested
                  tradeStablecoin:
                    requested: false
                    status: unrequested
                  transferCrypto:
                    requested: true
                    status: pending
                  transferFiat:
                    requested: false
                    status: unrequested
                  transferStablecoin:
                    requested: false
                    status: unrequested
                requirements:
                  firstName:
                    status: due
                    impact:
                      - custodyCrypto
                      - transferCrypto
                  lastName:
                    status: due
                    impact:
                      - custodyCrypto
                      - transferCrypto
                  ssnLast4:
                    status: due
                createdAt: '2026-01-10T14:25:00Z'
                updatedAt: '2026-01-10T14:25:00Z'
        '400':
          description: |-
            Invalid request. `unsupported_tos_language` is returned when a
            `tosAcceptances[].language` is not published for the matching
            `versionId` (i.e. not listed under `Customer.requirements.tos.tosVersions[].languages`).
            Other validation failures return `invalid_request`. See
            `x-error-instructions` on `ErrorType` for remediation steps;
            `errorMessage` carries human-readable detail. Missing Terms of
            Service acceptances are surfaced on `Customer.requirements.tos.tosVersions[]`
            (returned on success) rather than as an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  summary: Generic invalid request
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid customer creation request.
                unsupported_tos_language:
                  summary: A `tosAcceptances[].language` is not in the matching version's `languages`
                  value:
                    errorType: unsupported_tos_language
                    errorMessage: 'Terms of Service version ''us_individual_2026-05-29'' is not published in language ''fr''. Supported languages: [''en''].'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    get:
      summary: List customers
      description: |
        List all customers. The API will return all customers that the API Key has
        permissions to access. Results are not returned in any guaranteed order.
      operationId: listCustomers
      x-audience: public
      x-required-permissions:
        permissions:
          - customers:read@entity
        enforcement: any
      tags:
        - Customers
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully listed customers.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - customers
                    properties:
                      customers:
                        type: array
                        description: The list of customers.
                        items:
                          $ref: '#/components/schemas/Customer'
                  - $ref: '#/components/schemas/ListResponse'
              example:
                customers:
                  - customerId: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    type: individual
                    individual:
                      firstName: Jane
                      lastName: Doe
                      email: jane.doe@example.com
                    capabilities:
                      custodyCrypto:
                        requested: true
                        status: active
                      custodyFiat:
                        requested: false
                        status: unrequested
                      custodyStablecoin:
                        requested: false
                        status: unrequested
                      tradeCrypto:
                        requested: true
                        status: pending
                      tradeStablecoin:
                        requested: false
                        status: unrequested
                      transferCrypto:
                        requested: true
                        status: active
                      transferFiat:
                        requested: false
                        status: unrequested
                      transferStablecoin:
                        requested: false
                        status: unrequested
                    requirements:
                      fullSsn:
                        status: rejected
                        impact:
                          - tradeCrypto
                      sourceOfFunds:
                        status: due
                      citizenship:
                        status: due
                      tos:
                        status: due
                        impact:
                          - tradeCrypto
                          - transferFiat
                        tosVersions:
                          - versionId: us_individual_2026-05-29
                            languages:
                              - en
                            url: https://docs.cdp.coinbase.com/legal/terms/us_individual
                    createdAt: '2026-01-10T14:25:00Z'
                    updatedAt: '2026-01-10T14: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 request. Please check the request body and parameters.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/customers/{customerId}:
    get:
      summary: Get a customer
      description: |
        Get a customer by their ID. Returns the full customer object.
      operationId: getCustomerById
      x-audience: public
      x-required-permissions:
        permissions:
          - customers:read@entity
        enforcement: any
      tags:
        - Customers
      security:
        - apiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          description: The ID of the customer.
          schema:
            $ref: '#/components/schemas/CustomerId'
          example: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
      responses:
        '200':
          description: Successfully retrieved customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                customerId: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                type: individual
                individual:
                  firstName: Jane
                  lastName: Doe
                  email: jane.doe@example.com
                capabilities:
                  custodyCrypto:
                    requested: true
                    status: active
                  custodyFiat:
                    requested: false
                    status: unrequested
                  custodyStablecoin:
                    requested: false
                    status: unrequested
                  tradeCrypto:
                    requested: true
                    status: pending
                  tradeStablecoin:
                    requested: false
                    status: unrequested
                  transferCrypto:
                    requested: true
                    status: active
                  transferFiat:
                    requested: false
                    status: unrequested
                  transferStablecoin:
                    requested: false
                    status: unrequested
                requirements:
                  fullSsn:
                    status: rejected
                    impact:
                      - tradeCrypto
                  sourceOfFunds:
                    status: due
                  citizenship:
                    status: due
                  tos:
                    status: due
                    impact:
                      - tradeCrypto
                      - transferFiat
                    tosVersions:
                      - versionId: us_individual_2026-05-29
                        languages:
                          - en
                        url: https://docs.cdp.coinbase.com/legal/terms/us_individual
                createdAt: '2026-01-10T14:25:00Z'
                updatedAt: '2026-01-10T14:30:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Customer not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Customer not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    delete:
      summary: Delete a customer
      description: |
        Initiates deletion of the customer and all associated data. This operation
        is idempotent — repeated calls for an already-deleted customer return 204.
        A 404 is returned only when no customer with the given ID exists for the
        caller's entity.
      operationId: deleteCustomerById
      x-audience: public
      x-required-permissions:
        permissions:
          - customers:write@entity
        enforcement: any
      tags:
        - Customers
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: customerId
          in: path
          required: true
          description: The ID of the customer.
          schema:
            $ref: '#/components/schemas/CustomerId'
          example: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
      responses:
        '204':
          description: Customer deletion initiated successfully.
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: No customer with the given ID exists for the caller's entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Customer not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      summary: Update a customer
      description: |
        Update customer information and/or request capability changes.
        This endpoint supports partial updates. Provide only the fields you wish to change.
      operationId: updateCustomerById
      x-audience: public
      x-required-permissions:
        permissions:
          - customers:write@entity
        enforcement: any
      tags:
        - Customers
      security:
        - apiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          required: true
          description: The ID of the customer.
          schema:
            $ref: '#/components/schemas/CustomerId'
          example: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: |
          Customer fields to update. All fields are optional; omit a field to
          leave it unchanged.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
            examples:
              requestCapability:
                summary: Request a capability
                value:
                  capabilities:
                    custodyFiat:
                      requested: true
              submitRequirements:
                summary: Submit verification requirements
                value:
                  individual:
                    firstName: Jane
                    lastName: Doe
                    fullSsn: 123-45-6789
                    address:
                      line1: 123 Main St
                      city: New York
                      state: NY
                      postCode: '10001'
                      countryCode: US
                  tosAcceptances:
                    - versionId: us_individual_2026-05-29
                      language: en
                      acceptedAt: '2026-04-10T12:00:00Z'
                  taxAttestations:
                    - form: us_w9
                      isExemptBackupWithholding: true
                      edeliveryConsent: true
                      acceptedAt: '2026-04-17T20:00:00Z'
              requestWithRequirements:
                summary: Request capability with verification requirements
                value:
                  capabilities:
                    custodyFiat:
                      requested: true
                  individual:
                    firstName: Jane
                    lastName: Doe
                    dateOfBirth:
                      day: '15'
                      month: '01'
                      year: '1990'
      responses:
        '200':
          description: Successfully updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                customerId: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                type: individual
                individual: {}
                capabilities:
                  custodyCrypto:
                    requested: true
                    status: active
                  custodyFiat:
                    requested: true
                    status: pending
                  custodyStablecoin:
                    requested: false
                    status: unrequested
                  tradeCrypto:
                    requested: false
                    status: unrequested
                  tradeStablecoin:
                    requested: false
                    status: unrequested
                  transferCrypto:
                    requested: true
                    status: active
                  transferFiat:
                    requested: false
                    status: unrequested
                  transferStablecoin:
                    requested: false
                    status: unrequested
                requirements:
                  dateOfBirth:
                    status: pending
                    impact:
                      - custodyFiat
                  sourceOfFunds:
                    status: due
                createdAt: '2026-01-10T14:25:00Z'
                updatedAt: '2026-01-10T14:25:00Z'
        '400':
          description: |-
            Invalid request. `unsupported_tos_language` is returned when a
            `tosAcceptances[].language` is not published for the matching
            `versionId` (i.e. not listed under `Customer.requirements.tos.tosVersions[].languages`).
            Other validation failures return `invalid_request`. See
            `x-error-instructions` on `ErrorType` for remediation steps;
            `errorMessage` carries human-readable detail. Missing Terms of
            Service acceptances are surfaced on `Customer.requirements.tos.tosVersions[]`
            (returned on success) rather than as an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  summary: Generic invalid request
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
                unsupported_tos_language:
                  summary: A `tosAcceptances[].language` is not in the matching version's `languages`
                  value:
                    errorType: unsupported_tos_language
                    errorMessage: 'Terms of Service version ''us_individual_2026-05-29'' is not published in language ''fr''. Supported languages: [''en''].'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: The customer cannot be modified at this time. This may occur when one or more capabilities are permanently inactive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                customer_not_modifiable:
                  value:
                    errorType: forbidden
                    errorMessage: This customer cannot be modified at this time.
        '404':
          description: Customer not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Customer not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '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: []
      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'
                fiat:
                  summary: Fiat deposit destination
                  x-audience: public
                  value:
                    depositDestinations:
                      - depositDestinationId: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
                        accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                        type: fiat
                        status: active
                        fiat:
                          accountType: us_bank
                          currency: usd
                          bankName: Citibank, N.A.
                          beneficiaryName: John Smith
                          routingNumber: '987654321'
                          accountNumber: '123456789'
                          bankAddress: 399 Park Avenue, New York, NY 10022
                          supportedRails:
                            - ach
                        target:
                          accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                          asset: usdc
                        metadata:
                          customer_id: 123e4567-e89b-12d3-a456-426614174000
                        createdAt: '2025-06-01T00:00:00Z'
                        updatedAt: '2025-06-01T00:00: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. Two types are supported:

        - `crypto` (public): provisions a cryptocurrency address on the requested
          network. The returned `crypto.address` is the deposit address; funds
          sent to it are credited to the `target` account in the specified asset.
          For Customer-owned accounts, the Customer must have the `custodyCrypto`
          and `custodyStablecoin` capabilities enabled.


        - `fiat` (private-beta): provisions a bank
          account at a CDP banking partner. The server picks the account type
          (e.g. `us_bank`) and supported payment rails based on the account's
          eligibility; pass `fiat.paymentRail` to influence partner selection.
          The returned `fiat` object contains the bank account details the
          depositor needs to send funds. For Customer-owned accounts, the Customer
          must have the `custodyFiat` capability enabled. Requires account
          enablement — contact your Coinbase representative for access. Fields
          and behavior may change before general availability.


        For Customer-owned accounts not authorized for the required capabilities,
        the request is rejected with `customer_not_authorized` (HTTP 403).


        The created destination's `status` starts as `pending` for fiat (it
        becomes `active` once the partner provisioning callback completes) and
        `active` for crypto.
      operationId: createDepositDestination
      x-audience: public
      x-required-permissions:
        permissions:
          - accounts:write@entity
        enforcement: any
      tags:
        - Deposit Destinations
      security:
        - apiKeyAuth: []
      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
              fiat:
                summary: Create a fiat deposit destination
                x-audience: public
                value:
                  accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                  type: fiat
                  fiat:
                    currency: usd
                    paymentRail: ach
                  target:
                    accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    asset: usdc
                  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'
                fiat:
                  summary: Fiat deposit destination
                  x-audience: public
                  value:
                    depositDestinationId: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
                    accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    type: fiat
                    status: pending
                    fiat:
                      accountType: us_bank
                      currency: usd
                      bankName: Citibank, N.A.
                      beneficiaryName: John Smith
                      routingNumber: '987654321'
                      accountNumber: '123456789'
                      bankAddress: 399 Park Avenue, New York, NY 10022
                      supportedRails:
                        - ach
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    metadata:
                      customer_id: 123e4567-e89b-12d3-a456-426614174000
                    createdAt: '2025-06-01T00:00:00Z'
                    updatedAt: '2025-06-01T00:00: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
                      - custodyStablecoin
        '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: []
      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'
                fiat:
                  summary: Fiat deposit destination
                  x-audience: public
                  value:
                    depositDestinationId: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
                    accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    type: fiat
                    status: active
                    fiat:
                      accountType: us_bank
                      currency: usd
                      bankName: Citibank, N.A.
                      beneficiaryName: John Smith
                      routingNumber: '987654321'
                      accountNumber: '123456789'
                      bankAddress: 399 Park Avenue, New York, NY 10022
                      supportedRails:
                        - ach
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    metadata:
                      customer_id: 123e4567-e89b-12d3-a456-426614174000
                    createdAt: '2025-06-01T00:00:00Z'
                    updatedAt: '2025-06-01T00:00: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: []
      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
                attestVerifiedWalletOwnership: 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.
                  virtualAssetServiceProvider:
                    identifier: 5493001KJTIIGC8Y1R17
                    name: Fidelity Digital Asset Services, LLC
                    address:
                      line1: 123 Market St
                      line2: Suite 400
                      city: San Francisco
                      state: California
                      postCode: '94105'
                      countryCode: US
                  personalId: 123-45-6789
                  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=<ID>` - All transfers where the account is either source or target (OR semantics).
        * `?sourceAccountId=<ID>` - Only transfers where the account is the source (outbound).
        * `?targetAccountId=<ID>` - 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.
        Supported asset symbols include `usdc`, `eurc`, `usd`, and `eur`.

        **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: []
      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`, `eurc`, `eur`).
          example: usd
          schema:
            type: string
        - name: targetAsset
          in: query
          required: false
          description: Filter transfers by target asset symbol (e.g., `usdc`, `eurc`, `usd`, `eur`).
          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: []
      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: []
      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: []
      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:
              isSelf: false
              isIntermediary: true
              attestVerifiedWalletOwnership: true
              originator:
                name: John Doe
                address:
                  line1: 123 Main St
                  city: San Francisco
                  state: CA
                  postCode: '94105'
                  countryCode: US
                financialInstitution: PayPal, Inc.
                virtualAssetServiceProvider:
                  identifier: 5493001KJTIIGC8Y1R17
                  name: Fidelity Digital Asset Services, LLC
                personalId: 123-45-6789
                dateOfBirth:
                  day: '15'
                  month: '08'
                  year: '1990'
                walletType: custodial
              beneficiary:
                name: Jane Smith
      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: public
      tags:
        - Payment Sessions
      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://payments.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://payments.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
                    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://payments.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: public
      tags:
        - Payment Sessions
      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://payments.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://payments.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: public
      tags:
        - Payment Sessions
      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://payments.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://payments.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: public
      tags:
        - Payment Sessions
      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://payments.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://payments.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`. When an address is ineligible because of `insufficient_funds`, its `fundsRequired` array lists, per enabled (network, asset) combination, the current balance and required balance the payer needs to become eligible.
      operationId: getWalletAuthorizationOptions
      x-audience: public
      tags:
        - Payment Sessions
      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: An eligible option is available; a second wallet is superseded
                  description: 'The request supplied two payer addresses that both hold the session asset (USDC). The engine returns at most one option per asset, selecting the higher-priority source, so a single option appears in `options`. The other address appears in `ineligibleAddresses` with `code: superseded_by_preferred_option`.'
                  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'
                    ineligibleAddresses:
                      - address: '0xDeF9876543210FeDcBa9876543210FedcBa987654'
                        code: superseded_by_preferred_option
                        message: A preferred payment option was available from another wallet.
                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_be5160f4-c290-4b11-fac3-aaa66b379558
                            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.
                        fundsRequired:
                          - asset: usdc
                            network: base
                            currentBalance: '0.40'
                            requiredBalance: '1.00'
                          - asset: usdc
                            network: ethereum
                            currentBalance: '0.00'
                            requiredBalance: '1.00'
                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.
                        fundsRequired:
                          - asset: usdc
                            network: base
                            currentBalance: '0.40'
                            requiredBalance: '1.00'
                          - asset: usdc
                            network: ethereum
                            currentBalance: '0.00'
                            requiredBalance: '1.00'
                      - address: '0xDeF9876543210FeDcBa9876543210FedcBa987654'
                        code: insufficient_funds
                        message: The payer does not have sufficient funds.
                        fundsRequired:
                          - asset: usdc
                            network: base
                            currentBalance: '0.00'
                            requiredBalance: '1.00'
                          - asset: usdc
                            network: ethereum
                            currentBalance: '0.00'
                            requiredBalance: '1.00'
        '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: public
      tags:
        - Payment Sessions
      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: public
      tags:
        - Payment Sessions
      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: public
      tags:
        - Payment Sessions
      security: []
      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: public
      tags:
        - Payment Sessions
      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_reference: 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: public
      tags:
        - Payment Sessions
      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_reference: 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: public
      tags:
        - Payment Sessions
      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_reference: 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_reference: 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: public
      tags:
        - Payment Sessions
      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_reference: 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: public
      tags:
        - Payment Sessions
      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_reference: 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: public
      tags:
        - Payment Sessions
      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: public
      tags:
        - Payment Sessions
      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: public
      tags:
        - Payment Sessions
      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: public
      tags:
        - Payment Sessions
      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_reference: 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_reference: 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: public
      tags:
        - Payment Sessions
      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_reference: 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: public
      tags:
        - Payment Sessions
      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_reference: 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: public
      tags:
        - Disbursements
      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: public
      tags:
        - Disbursements
      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: public
      tags:
        - Disbursements
      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/end-users:
    post:
      summary: Create end user
      description: |-
        Creates an end user. An end user is an entity that can own CDP EVM accounts, EVM smart accounts, and/or Solana accounts. 1 or more authentication methods must be associated with an end user. By default, no accounts are created unless the optional `evmAccount` and/or `solanaAccount` fields are provided.
        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: createEndUser
      tags:
        - End User Account Management
      x-audience: public
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  description: |-
                    A stable, unique identifier for the end user. The `userId` must be unique across all end users in the developer's CDP Project. It must be between 1 and 100 characters long and can only contain alphanumeric characters and hyphens.

                    If `userId` is not provided in the request, the server will generate a random UUID.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
                authenticationMethods:
                  $ref: '#/components/schemas/AuthenticationMethods'
                evmAccount:
                  type: object
                  description: Configuration for creating an EVM account for the end user.
                  properties:
                    createSmartAccount:
                      type: boolean
                      description: If true, creates an EVM smart account and a default EVM EOA account as the owner. If false, only a EVM EOA account is created.
                      default: false
                      example: true
                    enableSpendPermissions:
                      type: boolean
                      description: If true, enables spend permissions for the EVM smart account.
                      example: true
                solanaAccount:
                  type: object
                  description: Configuration for creating a Solana account for the end user.
                  properties:
                    createSmartAccount:
                      type: boolean
                      description: Only false is a valid option since currently smart accounts on Solana are not supported.
                      default: false
                      example: false
              required:
                - authenticationMethods
            examples:
              default_behavior:
                summary: Default (no accounts created)
                value:
                  authenticationMethods:
                    - type: email
                      email: user@example.com
              evm_only:
                summary: EVM account only
                value:
                  authenticationMethods:
                    - type: email
                      email: user@example.com
                  evmAccount: {}
              evm_with_smart_account:
                summary: EVM only with smart account
                value:
                  authenticationMethods:
                    - type: email
                      email: user@example.com
                  evmAccount:
                    createSmartAccount: true
              solana_only:
                summary: Solana account only
                value:
                  authenticationMethods:
                    - type: sms
                      phoneNumber: '+15555551234'
                  solanaAccount:
                    createSmartAccount: false
              evm_and_solana:
                summary: Both EVM and Solana accounts
                value:
                  authenticationMethods:
                    - type: sms
                      phoneNumber: '+15555551234'
                  evmAccount:
                    createSmartAccount: true
                  solanaAccount:
                    createSmartAccount: false
      responses:
        '201':
          description: Successfully created end user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
              examples:
                default_no_accounts:
                  summary: Default behavior - No accounts created
                  value:
                    userId: user-001
                    authenticationMethods:
                      - type: email
                        email: user@example.com
                    evmAccounts: []
                    evmAccountObjects: []
                    evmSmartAccounts: []
                    evmSmartAccountObjects: []
                    solanaAccounts: []
                    solanaAccountObjects: []
                    createdAt: '2025-11-17T10:00:00Z'
                evm_smart_account_only:
                  summary: EVM smart account only
                  value:
                    userId: user-003
                    authenticationMethods:
                      - type: email
                        email: user@example.com
                    evmAccounts:
                      - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                    evmAccountObjects:
                      - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        createdAt: '2025-11-17T10:00:00Z'
                    evmSmartAccounts:
                      - '0x842d35Cc6634C0532925a3b844Bc454e4438f55f'
                    evmSmartAccountObjects:
                      - address: '0x842d35Cc6634C0532925a3b844Bc454e4438f55f'
                        ownerAddresses:
                          - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        createdAt: '2025-11-17T10:00:00Z'
                    solanaAccounts: []
                    solanaAccountObjects: []
                    createdAt: '2025-11-17T10:00:00Z'
                solana_only:
                  summary: Solana account only
                  value:
                    userId: user-004
                    authenticationMethods:
                      - type: sms
                        phoneNumber: '+15555551234'
                    evmAccounts: []
                    evmAccountObjects: []
                    evmSmartAccounts: []
                    evmSmartAccountObjects: []
                    solanaAccounts:
                      - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                    solanaAccountObjects:
                      - address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                        createdAt: '2025-11-17T10:00:00Z'
                    createdAt: '2025-11-17T10:00:00Z'
                evm_no_smart_account:
                  summary: EVM without smart account
                  value:
                    userId: user-004
                    authenticationMethods:
                      - type: email
                        email: user@example.com
                    evmAccounts:
                      - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                    evmAccountObjects:
                      - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        createdAt: '2025-11-17T10:00:00Z'
                    evmSmartAccounts: []
                    evmSmartAccountObjects: []
                    solanaAccounts: []
                    solanaAccountObjects: []
                    createdAt: '2025-11-17T10:00:00Z'
                multiple_accounts:
                  summary: End user with multiple accounts created
                  value:
                    userId: user-005
                    authenticationMethods:
                      - type: email
                        email: user@example.com
                    evmAccounts:
                      - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                      - '0x8F2A9B5C3D4E6F7A8B9C0D1E2F3A4B5C6D7E8F9A'
                      - '0xA1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0'
                    evmAccountObjects:
                      - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        createdAt: '2025-11-17T10:00:00Z'
                      - address: '0x8F2A9B5C3D4E6F7A8B9C0D1E2F3A4B5C6D7E8F9A'
                        createdAt: '2025-11-17T10:05:00Z'
                      - address: '0xA1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0'
                        createdAt: '2025-11-17T10:10:00Z'
                    evmSmartAccounts:
                      - '0x842d35Cc6634C0532925a3b844Bc454e4438f55f'
                      - '0x9D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B9C0D1E'
                    evmSmartAccountObjects:
                      - address: '0x842d35Cc6634C0532925a3b844Bc454e4438f55f'
                        ownerAddresses:
                          - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        createdAt: '2025-11-17T10:02:00Z'
                      - address: '0x9D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B9C0D1E'
                        ownerAddresses:
                          - '0x8F2A9B5C3D4E6F7A8B9C0D1E2F3A4B5C6D7E8F9A'
                        createdAt: '2025-11-17T10:07:00Z'
                    solanaAccounts:
                      - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                      - 9ZN8wT6gKxLmJvP4rQnYt7VxKwL3mN9rT8Qx2WzJpK5s
                    solanaAccountObjects:
                      - address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                        createdAt: '2025-11-17T10:15:00Z'
                      - address: 9ZN8wT6gKxLmJvP4rQnYt7VxKwL3mN9rT8Qx2WzJpK5s
                        createdAt: '2025-11-17T10:20:00Z'
                    createdAt: '2025-11-17T10:00:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: At least one authentication method must be provided.
                solana_smart_account_not_supported:
                  value:
                    errorType: invalid_request
                    errorMessage: The request contains one or more unsupported options.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      x-audience: public
      summary: List end users
      description: |-
        Lists the end users belonging to the developer's CDP Project.
        By default, the response is sorted by creation date in ascending order and paginated to 20 users per page.
      operationId: listEndUsers
      tags:
        - End User Account Management
      security:
        - apiKeyAuth: []
      parameters:
        - name: pageSize
          description: The number of end users 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 desired page of end users. Will be empty if there are no more end users to fetch.
          in: query
          required: false
          schema:
            type: string
          example: eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ==
        - name: sort
          description: Sort end users. Defaults to ascending order (oldest first).
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - createdAt=asc
                - createdAt=desc
          example:
            - createdAt=asc
          style: form
          explode: false
      responses:
        '200':
          description: Successfully retrieved end users.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - endUsers
                    properties:
                      endUsers:
                        type: array
                        description: The list of end users.
                        items:
                          $ref: '#/components/schemas/EndUser'
                  - $ref: '#/components/schemas/ListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid project ID.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/end-users/auth/validate-token:
    post:
      x-audience: public
      summary: Validate end user access token
      description: |-
        Validates the end user's access token and returns the end user's information. Returns an error if the access token is invalid or expired.

        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: validateEndUserAccessToken
      tags:
        - End User Account Management
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: The request body for a developer to verify an end user's access token.
              properties:
                accessToken:
                  type: string
                  description: The access token in JWT format to verify.
                  example: eyJhbGciOiJFUzI1NiIsImtpZCI6IjA1ZGNmYTU1LWY1NzktNDg5YS1iNThhLTFlMDI5Nzk0N2VlNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjZHAtYXBpIiwiYXV0aF90eXBlIjoiZW1haWwiLCJleHAiOjE3NTM5ODAyOTksImlhdCI6MTc1Mzk3ODQ5OSwiaXNzIjoiY2RwLWFwaSIsImp0aSI6IjA3ZWY5M2JlLTYzMDQtNGQ1YS05NmE3LWJlMGI5MWI0ZTE3NCIsInByb2plY3RfaWQiOiJjNzRkOGI4OC0wOTNiLTQyZDItOGE4Yy1kZGM1YzVlMGViNDMiLCJzdWIiOiJjYTM4YTM4ZC0xNmE5LTRkMjYtYTcxZC0zOWY2NmY5YzZiN2UifQ.1SU0pOy-WR002qUw4hd_UmZWRSLz-ZL6v7PvQvZMKVE6a51x_tqeUeRGaTGuYl1whg0eccMObmK7FqXKRH6E4g
              required:
                - accessToken
      responses:
        '200':
          description: Confirms that the access token is valid and returns the end user's information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          description: Request body is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Missing access token.
        '401':
          description: Request is not properly authenticated, or the access token is invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: 'Invalid JWT issuer: not-cdp-api, expected: cdp-api.'
        '404':
          description: End user not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/end-users/{userId}:
    get:
      x-audience: public
      summary: Get end user
      description: |-
        Gets an end user by ID.

        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: getEndUser
      tags:
        - End User Account Management
      security:
        - apiKeyAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the end user to get.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
          example: e051beeb-7163-4527-a5b6-35e301529ff2
      responses:
        '200':
          description: Successfully got end user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user with the given ID not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/end-users/lookup:
    get:
      x-audience: public
      summary: Look up end users by identity
      description: |-
        Looks up end users. Exactly one lookup type must be provided per request:

        - **email**: searches across all email-based authentication methods
          (email, Google, Apple, GitHub). May return multiple end users if the
          same email address appears across different auth methods.

        - **oauthProvider + oauthSubject**: looks up a user by their OAuth
          provider and subject (the `sub` claim from the provider's ID token).
          Both params must be provided together.

        - **phoneNumber**: looks up a user by their SMS-verified phone number.
        - **siweAddress**: looks up a user by the Ethereum address they authenticated
          with via Sign In With Ethereum (EIP-4361).


        Returns all matching end users. If no end users match, an empty array is returned.

        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: lookupEndUser
      tags:
        - End User Account Management
      security:
        - apiKeyAuth: []
      parameters:
        - name: email
          in: query
          required: false
          description: The email address to search for across all email-based authentication methods.
          schema:
            $ref: '#/components/schemas/Email'
          example: user@example.com
        - name: oauthProvider
          in: query
          required: false
          description: The OAuth provider to search by. Must be provided together with oauthSubject.
          schema:
            $ref: '#/components/schemas/OAuth2ProviderType'
          example: google
        - name: oauthSubject
          in: query
          required: false
          description: The OAuth subject (the `sub` claim from the provider's ID token). Must be provided together with oauthProvider.
          schema:
            type: string
          example: '1234567890'
        - name: phoneNumber
          in: query
          required: false
          description: The E.164-formatted phone number to search for. Must be URL-encoded when passed as a query parameter (e.g. `+14155552671` → `%2B14155552671`).
          schema:
            $ref: '#/components/schemas/PhoneNumber'
          example: '+14155552671'
        - name: siweAddress
          in: query
          required: false
          description: The ERC-55 checksummed Ethereum address to search for. Looks up a user by the address they authenticated with via Sign In With Ethereum (EIP-4361).
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      responses:
        '200':
          description: Successfully looked up end users.
          content:
            application/json:
              schema:
                type: object
                required:
                  - endUsers
                properties:
                  endUsers:
                    type: array
                    description: The list of end users matching the lookup.
                    items:
                      $ref: '#/components/schemas/EndUser'
              examples:
                email_match:
                  summary: End user found by email
                  value:
                    endUsers:
                      - userId: user-001
                        authenticationMethods:
                          - type: email
                            email: user@example.com
                        evmAccounts: []
                        evmAccountObjects: []
                        evmSmartAccounts: []
                        evmSmartAccountObjects: []
                        solanaAccounts: []
                        solanaAccountObjects: []
                        createdAt: '2025-11-17T10:00:00Z'
                multiple_email_matches:
                  summary: Multiple end users with same email across auth methods
                  value:
                    endUsers:
                      - userId: user-001
                        authenticationMethods:
                          - type: email
                            email: user@example.com
                        evmAccounts: []
                        evmAccountObjects: []
                        evmSmartAccounts: []
                        evmSmartAccountObjects: []
                        solanaAccounts: []
                        solanaAccountObjects: []
                        createdAt: '2025-11-17T10:00:00Z'
                      - userId: user-002
                        authenticationMethods:
                          - type: google
                            sub: google-sub-123
                            email: user@example.com
                        evmAccounts: []
                        evmAccountObjects: []
                        evmSmartAccounts: []
                        evmSmartAccountObjects: []
                        solanaAccounts: []
                        solanaAccountObjects: []
                        createdAt: '2025-11-17T11:00:00Z'
                oauth_match:
                  summary: End user found by OAuth subject
                  value:
                    endUsers:
                      - userId: user-003
                        authenticationMethods:
                          - type: google
                            sub: '1234567890'
                            email: user@example.com
                        evmAccounts: []
                        evmAccountObjects: []
                        evmSmartAccounts: []
                        evmSmartAccountObjects: []
                        solanaAccounts: []
                        solanaAccountObjects: []
                        createdAt: '2025-11-17T12:00:00Z'
                phone_match:
                  summary: End user found by phone number
                  value:
                    endUsers:
                      - userId: user-004
                        authenticationMethods:
                          - type: sms
                            phoneNumber: '+14155552671'
                        evmAccounts: []
                        evmAccountObjects: []
                        evmSmartAccounts: []
                        evmSmartAccountObjects: []
                        solanaAccounts: []
                        solanaAccountObjects: []
                        createdAt: '2025-11-17T13:00:00Z'
                siwe_match:
                  summary: End user found by SIWE address
                  value:
                    endUsers:
                      - userId: user-005
                        authenticationMethods:
                          - type: siwe
                            address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        evmAccounts: []
                        evmAccountObjects: []
                        evmSmartAccounts: []
                        evmSmartAccountObjects: []
                        solanaAccounts: []
                        solanaAccountObjects: []
                        createdAt: '2025-11-17T14:00:00Z'
                no_matches:
                  summary: No end users found
                  value:
                    endUsers: []
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no_lookup_param:
                  summary: No lookup parameter provided
                  value:
                    errorType: invalid_request
                    errorMessage: 'Exactly one lookup type must be provided: email, phoneNumber, siweAddress, or oauthProvider+oauthSubject.'
                multiple_lookup_params:
                  summary: Multiple lookup parameters provided
                  value:
                    errorType: invalid_request
                    errorMessage: 'Exactly one lookup type must be provided: email, phoneNumber, siweAddress, or oauthProvider+oauthSubject.'
                oauth_missing_subject:
                  summary: oauthProvider provided without oauthSubject
                  value:
                    errorType: invalid_request
                    errorMessage: oauthProvider and oauthSubject must be provided together.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/end-users/{userId}/evm:
    post:
      summary: Add EVM account to end user
      description: |-
        Adds a new EVM EOA account to an existing end user. End users can have up to 10 EVM accounts.
        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: addEndUserEvmAccount
      tags:
        - End User Account Management
      x-audience: public
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/EndUserUserId'
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
            examples:
              default:
                summary: Create EVM EOA account
                value: {}
      responses:
        '201':
          description: Successfully added EVM account to end user.
          content:
            application/json:
              schema:
                type: object
                required:
                  - evmAccount
                properties:
                  evmAccount:
                    $ref: '#/components/schemas/EndUserEvmAccount'
              examples:
                default:
                  summary: EVM EOA account created
                  value:
                    evmAccount:
                      address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                      createdAt: '2025-11-17T10:00:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                max_accounts_reached:
                  value:
                    errorType: invalid_request
                    errorMessage: Maximum number of EVM accounts (10) reached for this end user.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: End user not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user with the given ID not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/end-users/{userId}/evm-smart-account:
    post:
      summary: Add EVM smart account to end user
      description: |-
        Creates an EVM smart account for an existing end user. The backend will create a new EVM EOA account to serve as the owner of the smart account.
        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: addEndUserEvmSmartAccount
      tags:
        - End User Account Management
      x-audience: public
      security:
        - apiKeyAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the end user to add the smart account to.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
          example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                enableSpendPermissions:
                  type: boolean
                  description: If true, enables spend permissions for the EVM smart account.
                  default: false
                  example: true
            examples:
              default:
                summary: Create smart account
                value: {}
              with_spend_permissions:
                summary: Create smart account with spend permissions
                value:
                  enableSpendPermissions: true
      responses:
        '201':
          description: Successfully added EVM smart account to end user.
          content:
            application/json:
              schema:
                type: object
                required:
                  - evmSmartAccount
                properties:
                  evmSmartAccount:
                    $ref: '#/components/schemas/EndUserEvmSmartAccount'
              examples:
                default:
                  summary: EVM smart account created
                  value:
                    evmSmartAccount:
                      address: '0x842d35Cc6634C0532925a3b844Bc454e4438f55f'
                      ownerAddresses:
                        - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                      createdAt: '2025-11-17T10:00:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                max_accounts_reached:
                  value:
                    errorType: invalid_request
                    errorMessage: Maximum number of EVM smart accounts (10) reached for this end user.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: End user not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user with the given ID not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/end-users/{userId}/solana:
    post:
      summary: Add Solana account to end user
      description: |-
        Adds a new Solana account to an existing end user. End users can have up to 10 Solana accounts.
        This API is intended to be used by the developer's own backend, and is authenticated using the developer's CDP API key.
      operationId: addEndUserSolanaAccount
      tags:
        - End User Account Management
      x-audience: public
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/EndUserUserId'
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
            examples:
              default:
                summary: Create Solana account
                value: {}
      responses:
        '201':
          description: Successfully added Solana account to end user.
          content:
            application/json:
              schema:
                type: object
                required:
                  - solanaAccount
                properties:
                  solanaAccount:
                    $ref: '#/components/schemas/EndUserSolanaAccount'
              examples:
                default:
                  summary: Solana account created
                  value:
                    solanaAccount:
                      address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                      createdAt: '2025-11-17T10:00:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                max_accounts_reached:
                  value:
                    errorType: invalid_request
                    errorMessage: Maximum number of Solana accounts (10) reached for this end user.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: End user not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user with the given ID not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/end-users/import:
    post:
      summary: Import end user private key
      description: |-
        Imports an existing private key for an end user into the developer's CDP Project. The private key must be encrypted using the CDP SDK's encryption scheme before being sent to this endpoint. This API should be called from the [CDP SDK](https://github.com/coinbase/cdp-sdk) to ensure that the associated private key is properly encrypted.

        This endpoint allows developers to import existing keys for their end users, supporting both EVM and Solana key types. The end user must have at least one authentication method configured.
      operationId: importEndUser
      tags:
        - End User Account Management
      x-audience: public
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  description: A stable, unique identifier for the end user. The `userId` must be unique across all end users in the developer's CDP Project. It must be between 1 and 100 characters long and can only contain alphanumeric characters and hyphens.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
                authenticationMethods:
                  $ref: '#/components/schemas/AuthenticationMethods'
                encryptedPrivateKey:
                  type: string
                  description: The base64-encoded, encrypted private key to import. The private key must be encrypted using the CDP SDK's encryption scheme. This is a 32-byte raw private key.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                keyType:
                  type: string
                  description: The type of key being imported. Determines what type of account will be associated for the end user.
                  enum:
                    - evm
                    - solana
                  example: evm
              required:
                - userId
                - authenticationMethods
                - encryptedPrivateKey
                - keyType
            examples:
              import_evm_key:
                summary: Import an EVM private key
                value:
                  userId: user-001
                  authenticationMethods:
                    - type: email
                      email: user@example.com
                  encryptedPrivateKey: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                  keyType: evm
              import_solana_key:
                summary: Import a Solana private key
                value:
                  userId: user-002
                  authenticationMethods:
                    - type: sms
                      phoneNumber: '+15555551234'
                  encryptedPrivateKey: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                  keyType: solana
              import_evm_key_with_jwt_auth:
                summary: Import an EVM private key with JWT authentication
                value:
                  userId: user-003
                  authenticationMethods:
                    - type: jwt
                      sub: e051beeb-7163-4527-a5b6-35e301529ff2
                      kid: NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg
                  encryptedPrivateKey: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                  keyType: evm
      responses:
        '201':
          description: Successfully imported key and created end user with the associated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
              examples:
                evm_key_imported:
                  summary: End user with imported EVM account
                  value:
                    userId: user-001
                    authenticationMethods:
                      - type: email
                        email: user@example.com
                    evmAccounts:
                      - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                    evmAccountObjects:
                      - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        createdAt: '2025-11-17T10:00:00Z'
                    evmSmartAccounts: []
                    evmSmartAccountObjects: []
                    solanaAccounts: []
                    solanaAccountObjects: []
                    createdAt: '2025-11-17T10:00:00Z'
                solana_key_imported:
                  summary: End user with imported Solana account
                  value:
                    userId: user-002
                    authenticationMethods:
                      - type: sms
                        phoneNumber: '+15555551234'
                    evmAccounts: []
                    evmAccountObjects: []
                    evmSmartAccounts: []
                    evmSmartAccountObjects: []
                    solanaAccounts:
                      - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                    solanaAccountObjects:
                      - address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                        createdAt: '2025-11-17T10:00:00Z'
                    createdAt: '2025-11-17T10:00:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_key:
                  value:
                    errorType: invalid_request
                    errorMessage: The encrypted private key is invalid.
                invalid_key_type:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid key type. Must be 'evm' or 'solana'.
                missing_auth_methods:
                  value:
                    errorType: invalid_request
                    errorMessage: At least one authentication method must be provided.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '409':
          description: Resource already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_exists:
                  value:
                    errorType: already_exists
                    errorMessage: An account with the given address already exists.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/sign/transaction:
    post:
      x-audience: public
      summary: Sign transaction via end user EVM account
      description: |-
        Signs a transaction with the given end user EVM account.
        The transaction should be serialized as a hex string using [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/).

        The transaction must be an [EIP-1559 dynamic fee transaction](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md). The developer is responsible for ensuring that the unsigned transaction is valid, as the API will not validate the transaction.
      operationId: signEvmTransactionWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          description: The ID of the end user.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The 0x-prefixed address of the EVM account belonging to the end user.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  pattern: ^0x[0-9a-fA-F]{40}$
                transaction:
                  type: string
                  description: The RLP-encoded transaction to sign, as a 0x-prefixed hex string.
                  example: '0xf86b098505d21dba00830334509431415daf58e2c6b7323b4c58712fd92952145da79018080'
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - address
                - transaction
      responses:
        '200':
          description: Successfully signed transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signedTransaction:
                    type: string
                    description: The RLP-encoded signed transaction, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signedTransaction
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/send/transaction:
    post:
      x-audience: public
      summary: Send transaction via end user EVM account
      description: |-
        Signs a transaction with the given end user EVM account and sends it to the indicated supported network. This API handles nonce management and gas estimation, leaving the developer to provide only the minimal set of fields necessary to send the transaction. The transaction should be serialized as a hex string using [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/).

        The transaction must be an [EIP-1559 dynamic fee transaction](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md).


        **Transaction fields and API behavior**

        - `to` *(Required)*: The address of the contract or account to send the transaction to.
        - `chainId` *(Ignored)*: The value of the `chainId` field in the transaction is ignored.
          The transaction will be sent to the network indicated by the `network` field in the request body.

        - `nonce` *(Optional)*: The nonce to use for the transaction. If not provided, the API will assign
           a nonce to the transaction based on the current state of the account.

        - `maxPriorityFeePerGas` *(Optional)*: The maximum priority fee per gas to use for the transaction.
           If not provided, the API will estimate a value based on current network conditions.

        - `maxFeePerGas` *(Optional)*: The maximum fee per gas to use for the transaction.
           If not provided, the API will estimate a value based on current network conditions.

        - `gasLimit` *(Optional)*: The gas limit to use for the transaction. If not provided, the API will estimate a value
          based on the `to` and `data` fields of the transaction.

        - `value` *(Optional)*: The amount of ETH, in wei, to send with the transaction.
        - `data` *(Optional)*: The data to send with the transaction; only used for contract calls.
        - `accessList` *(Optional)*: The access list to use for the transaction.
      operationId: sendEvmTransactionWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          description: The ID of the end user.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The 0x-prefixed address of the EVM account belonging to the end user.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  pattern: ^0x[0-9a-fA-F]{40}$
                network:
                  type: string
                  description: The network to send the transaction to.
                  enum:
                    - base
                    - base-sepolia
                    - ethereum
                    - ethereum-sepolia
                    - avalanche
                    - polygon
                    - optimism
                    - arbitrum
                    - arbitrum-sepolia
                    - world
                    - world-sepolia
                  example: base-sepolia
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
                transaction:
                  type: string
                  description: The RLP-encoded transaction to sign and send, as a 0x-prefixed hex string.
                  example: '0xf86b098505d21dba00830334509431415daf58e2c6b7323b4c58712fd92952145da79018080'
              required:
                - address
                - transaction
                - network
      responses:
        '200':
          description: Successfully signed and sent transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionHash:
                    type: string
                    description: The hash of the transaction, as a 0x-prefixed hex string.
                    example: '0xf8f98fb6726fc936f24b2007df5cb20e2b8444ff3dfaa2a929335f432a9be2e7'
                required:
                  - transactionHash
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/{address}/send/{asset}:
    post:
      x-audience: public
      summary: Send USDC on EVM
      description: |-
        Sends USDC from an end user's EVM account (EOA or Smart Account) to a recipient address on a supported EVM network. This endpoint simplifies USDC transfers by automatically handling contract resolution, decimal conversion, gas estimation, and transaction encoding.
        The `amount` field accepts human-readable amounts as decimal strings (e.g., "1.5", "25.50").
      operationId: sendEvmAssetWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
          example: e051beeb-7163-4527-a5b6-35e301529ff2
        - name: address
          description: The 0x-prefixed address of the EVM account (EOA or Smart Account) to send USDC from. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/BlockchainAddress'
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: asset
          in: path
          required: true
          description: The asset to send. Currently only "usdc" is supported.
          schema:
            allOf:
              - $ref: '#/components/schemas/Asset'
            enum:
              - usdc
          example: usdc
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  allOf:
                    - $ref: '#/components/schemas/BlockchainAddress'
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: The 0x-prefixed address of the recipient.
                  example: '0x1234567890123456789012345678901234567890'
                amount:
                  type: string
                  minLength: 1
                  maxLength: 32
                  description: The amount of USDC to send as a decimal string (e.g., "1.5" or "25.50").
                  example: '1.50'
                network:
                  type: string
                  description: The EVM network to send USDC on.
                  enum:
                    - base
                    - base-sepolia
                    - ethereum
                    - ethereum-sepolia
                    - avalanche
                    - polygon
                    - optimism
                    - arbitrum
                    - arbitrum-sepolia
                    - world
                    - world-sepolia
                  example: base-sepolia
                useCdpPaymaster:
                  type: boolean
                  description: Whether to use CDP Paymaster to sponsor gas fees. Only applicable for EVM Smart Accounts. When true, the transaction gas will be paid by the Paymaster, allowing users to send USDC without holding native gas tokens. Ignored for EOA accounts. Cannot be used together with `paymasterUrl`.
                  example: true
                paymasterUrl:
                  allOf:
                    - $ref: '#/components/schemas/Url'
                  description: Optional custom Paymaster URL to use for gas sponsorship. Only applicable for EVM Smart Accounts. This allows you to use your own Paymaster service instead of CDP's Paymaster. Cannot be used together with `useCdpPaymaster`.
                  example: https://api.developer.coinbase.com/rpc/v1/base/AbCdEf123456
                paymasterContext:
                  $ref: '#/components/schemas/PaymasterContext'
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - to
                - amount
                - network
            examples:
              send_usdc_eoa:
                summary: Send USDC from EOA
                value:
                  to: '0x1234567890123456789012345678901234567890'
                  amount: '25.50'
                  network: base-sepolia
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
              send_usdc_smart_account_cdp_paymaster:
                summary: Send USDC from Smart Account with CDP Paymaster
                value:
                  to: '0x1234567890123456789012345678901234567890'
                  amount: '10.00'
                  network: base-sepolia
                  useCdpPaymaster: true
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
              send_usdc_smart_account_custom_paymaster:
                summary: Send USDC from Smart Account with custom Paymaster
                value:
                  to: '0x1234567890123456789012345678901234567890'
                  amount: '15.00'
                  network: base-sepolia
                  paymasterUrl: https://api.developer.coinbase.com/rpc/v1/base/AbCdEf123456
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
      responses:
        '200':
          description: Successfully sent transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionHash:
                    type: string
                    description: The hash of the transaction, as a 0x-prefixed hex string. Populated for EOA accounts. Null for Smart Accounts (use userOpHash instead).
                    example: '0xf8f98fb6726fc936f24b2007df5cb20e2b8444ff3dfaa2a929335f432a9be2e7'
                    nullable: true
                  userOpHash:
                    type: string
                    description: The hash of the user operation, as a 0x-prefixed hex string. Populated for Smart Accounts. Null for EOA accounts (use transactionHash instead).
                    example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                    nullable: true
              examples:
                eoa_transfer:
                  summary: EOA transfer response
                  value:
                    transactionHash: '0xf8f98fb6726fc936f24b2007df5cb20e2b8444ff3dfaa2a929335f432a9be2e7'
                    userOpHash: null
                smart_account_transfer:
                  summary: Smart Account transfer response
                  value:
                    transactionHash: null
                    userOpHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_amount:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid amount format. Amount must be a valid decimal string.
                    errorParam: amount
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                invalid_network:
                  value:
                    errorType: invalid_request
                    errorMessage: Unsupported network for USDC transfers.
                    errorParam: network
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                invalid_asset:
                  value:
                    errorType: invalid_request
                    errorMessage: Unsupported asset. Currently only 'usdc' is supported.
                    errorParam: asset
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                insufficient_balance:
                  value:
                    errorType: invalid_request
                    errorMessage: Account has insufficient USDC balance to complete the transfer.
                    errorParam: amount
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                conflicting_paymaster:
                  value:
                    errorType: invalid_request
                    errorMessage: Cannot specify both 'useCdpPaymaster' and 'paymasterUrl'. Please use only one.
                    errorLink: https://docs.cdp.coinbase.com/embedded-wallets/evm-features/smart-accounts#gas-sponsorship-with-paymaster
                paymaster_context_without_paymaster:
                  value:
                    errorType: invalid_request
                    errorMessage: 'paymasterContext requires a paymaster: set paymasterUrl or useCdpPaymaster.'
                    errorParam: paymasterContext
                    errorLink: https://docs.cdp.coinbase.com/embedded-wallets/evm-features/smart-accounts#gas-sponsorship-with-paymaster
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/sign/message:
    post:
      x-audience: public
      summary: Sign EIP-191 message via end user EVM account
      description: |-
        Signs an [EIP-191](https://eips.ethereum.org/EIPS/eip-191) message with the given end user EVM account.

        Per the specification, the message in the request body is prepended with `0x19 <0x45 (E)> <thereum Signed Message:\n" + len(message)>` before being signed.
      operationId: signEvmMessageWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          description: The ID of the end user.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The 0x-prefixed address of the EVM account belonging to the end user.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  pattern: ^0x[0-9a-fA-F]{40}$
                message:
                  type: string
                  description: The message to sign.
                  example: Hello, world!
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - address
                - message
      responses:
        '200':
          description: Successfully signed message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the message, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signature
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/sign/typed-data:
    post:
      x-audience: public
      summary: Sign EIP-712 typed data via end user EVM account
      description: Signs [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data with the given end user EVM account.
      operationId: signEvmTypedDataWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          description: The ID of the end user.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The 0x-prefixed address of the EVM account belonging to the end user.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  pattern: ^0x[0-9a-fA-F]{40}$
                typedData:
                  $ref: '#/components/schemas/EIP712Message'
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - address
                - typedData
      responses:
        '200':
          description: Successfully signed typed data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the typed data, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/delegation:
    get:
      x-audience: public
      summary: Get delegation for end user
      description: Returns the active delegation for the specified end user, if one exists. This operation can be performed by the end user themselves or by a developer using their API key.
      operationId: getDelegationForEndUser
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/ProjectIDOptional'
      responses:
        '200':
          description: Active delegation found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expiresAt:
                    type: string
                    format: date-time
                    description: The date until which the delegation is valid.
                    example: '2026-02-03T10:35:00Z'
                required:
                  - expiresAt
              example:
                expiresAt: '2026-02-03T10:35:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: No active delegation found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: No active delegation found for the specified end user.
                    errorParam: userId
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    delete:
      x-audience: public
      summary: Revoke delegation for end user
      description: Revokes all active delegations for the specified end user. This operation can be performed by the end user themselves or by a developer using their API key.
      operationId: revokeDelegationForEndUser
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/XDeveloperAuth'
          required: false
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                walletSecretId:
                  description: When revoking with a wallet authentication scheme, the ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
            example:
              walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
      responses:
        '204':
          description: Delegation revoked successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Delegation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: No active delegation found for the specified end user.
                    errorParam: userId
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/address/{address}/delegation:
    post:
      x-audience: public
      summary: Create account-scoped delegation for end user
      description: |-
        Creates an account-scoped delegation that allows a developer to sign on behalf of an end user for a single blockchain account (identified by its address) for the specified duration. The end user must be authenticated to authorize this delegation.
        Multiple account-scoped delegations may exist concurrently for a single end user (one per canonical account address). Account-scoped and user-scoped delegations cannot coexist for the same user.
        When the address corresponds to an EVM Smart Account, the delegation is scoped to the Smart Account's owner EOA rather than the Smart Account address itself. This means `/address/{smartAccountAddress}/delegation` and `/address/{ownerEoaAddress}/delegation` resolve to the same delegation, and the 409 `account_scoped_delegation_active` error may be returned when creating via either address if one already exists for the canonical owner.
      operationId: createDelegationForEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - name: address
          in: path
          required: true
          description: The blockchain address of the end user account to scope this delegation to. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana). For EVM addresses, matching is case-insensitive.
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                expiresAt:
                  type: string
                  format: date-time
                  description: The date until which the delegation is valid.
                  example: '2026-02-03T10:35:00Z'
                walletSecretId:
                  description: The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - expiresAt
                - walletSecretId
            example:
              expiresAt: '2026-02-03T10:35:00Z'
              walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
      responses:
        '201':
          description: Delegation created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expiresAt:
                    type: string
                    format: date-time
                    description: The date until which the delegation is valid.
                    example: '2026-02-03T10:35:00Z'
                required:
                  - expiresAt
              example:
                expiresAt: '2026-02-03T10:35:00Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_expiresAt:
                  value:
                    errorType: invalid_request
                    errorMessage: Field 'expiresAt' is required.
                    errorParam: expiresAt
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                invalid_expiresAt:
                  value:
                    errorType: invalid_request
                    errorMessage: Field 'expiresAt' must be a valid ISO 8601 string.
                    errorParam: expiresAt
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unknown_address:
                  value:
                    errorType: not_found
                    errorMessage: No account with the given address exists for this end user.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '409':
          description: Conflict with an existing delegation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                user_scoped_delegation_active:
                  value:
                    errorType: already_exists
                    errorMessage: A user-scoped delegation is already active for this user. Revoke it before creating an account-scoped delegation.
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#already-exists
                account_scoped_delegation_active:
                  value:
                    errorType: already_exists
                    errorMessage: An account-scoped delegation is already active for this address.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#already-exists
        '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: Too many requests. Please try again later.
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#rate-limit-exceeded
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    get:
      x-audience: public
      summary: Get account-scoped delegation for end user
      description: |-
        Returns the active account-scoped delegation for the specified end user account, if one exists. Useful for showing delegation status in a UI.
        When the address corresponds to an EVM Smart Account, this returns the delegation for the Smart Account's owner EOA.
      operationId: getDelegationForEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - name: address
          in: path
          required: true
          description: The blockchain address of the end user account to query. For EVM addresses, matching is case-insensitive.
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - $ref: '#/components/parameters/ProjectIDOptional'
      responses:
        '200':
          description: Active delegation found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expiresAt:
                    type: string
                    format: date-time
                    description: The date until which the delegation is valid.
                    example: '2026-02-03T10:35:00Z'
                required:
                  - expiresAt
              example:
                expiresAt: '2026-02-03T10:35:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: No active delegation found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: No active account-scoped delegation found for the specified address.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    delete:
      x-audience: public
      summary: Revoke account-scoped delegation for end user
      description: |-
        Revokes the active account-scoped delegation for the specified end user account. Other account-scoped delegations for the same user are unaffected. This operation can be performed by the end user themselves or by a developer using their API key.
        When the address corresponds to an EVM Smart Account, this revokes the delegation for the Smart Account's owner EOA.
      operationId: revokeDelegationForEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/XDeveloperAuth'
          required: false
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - name: address
          in: path
          required: true
          description: The blockchain address of the end user account whose delegation should be revoked. For EVM addresses, matching is case-insensitive.
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                walletSecretId:
                  description: When revoking with a wallet authentication scheme, the ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
            example:
              walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
      responses:
        '204':
          description: Delegation revoked successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Delegation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: No active account-scoped delegation found for the specified address.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/eip7702/delegation:
    post:
      x-audience: public
      summary: Create EIP-7702 delegation for end user EVM account
      description: |-
        Creates an EIP-7702 delegation for an end user's EVM EOA account, upgrading it with smart account capabilities.

        This endpoint:
        - Retrieves delegation artifacts from onchain
        - Signs the EIP-7702 authorization for delegation
        - Assembles and submits a Type 4 transaction
        - Creates an associated smart account object

        The delegation allows the EVM EOA to be used as a smart account, which enables batched transactions and gas sponsorship via paymaster.
      operationId: createEvmEip7702DelegationWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The 0x-prefixed address of the EVM account to delegate.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  pattern: ^0x[0-9a-fA-F]{40}$
                network:
                  $ref: '#/components/schemas/EvmEip7702DelegationNetwork'
                enableSpendPermissions:
                  type: boolean
                  description: Whether to configure spend permissions for the upgraded, delegated account. When enabled, the account can grant permissions for third parties to spend on its behalf.
                  example: true
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - address
                - network
      responses:
        '201':
          description: Delegation operation created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  delegationOperationId:
                    type: string
                    format: uuid
                    description: The unique identifier for the delegation operation. Use this to poll the operation status.
                    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                required:
                  - delegationOperationId
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_network:
                  value:
                    errorType: invalid_request
                    errorMessage: Field 'network' is required.
                    errorParam: network
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                unsupported_network:
                  value:
                    errorType: invalid_request
                    errorMessage: Network 'gnosis' is not supported for EIP-7702.
                    errorParam: network
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: EVM account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '409':
          description: Account already delegated on the given network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_delegated:
                  value:
                    errorType: already_exists
                    errorMessage: Account already has an active EIP-7702 delegation on the given network.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#already-exists
        '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: Too many requests. Please try again later.
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#rate-limit-exceeded
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/evm/smart-accounts/{address}/send:
    post:
      x-audience: public
      summary: Send user operation for end user Smart Account
      description: Prepares, signs, and sends a user operation for an end user's Smart Account.
      operationId: sendUserOperationWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - name: address
          description: The address of the EVM Smart Account to execute the user operation from.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  $ref: '#/components/schemas/EvmUserOperationNetwork'
                calls:
                  type: array
                  description: The list of calls to make from the Smart Account.
                  items:
                    $ref: '#/components/schemas/EvmCall'
                useCdpPaymaster:
                  type: boolean
                  description: Whether to use the CDP Paymaster for the user operation.
                  example: true
                paymasterUrl:
                  allOf:
                    - $ref: '#/components/schemas/Url'
                  description: The URL of the paymaster to use for the user operation. If using the CDP Paymaster, use the `useCdpPaymaster` option.
                  example: https://api.developer.coinbase.com/rpc/v1/base/<token>
                paymasterContext:
                  $ref: '#/components/schemas/PaymasterContext'
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
                dataSuffix:
                  type: string
                  pattern: ^0x[0-9a-fA-F]+$
                  description: The EIP-8021 data suffix (hex-encoded) that enables transaction attribution for the user operation.
                  example: '0xdddddddd62617365617070070080218021802180218021802180218021'
              required:
                - network
                - calls
                - useCdpPaymaster
      responses:
        '200':
          description: The user operation was successfully prepared, signed, and sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Field "network" is required.
                paymaster_context_without_paymaster:
                  value:
                    errorType: invalid_request
                    errorMessage: 'paymasterContext requires a paymaster: set paymasterUrl or useCdpPaymaster.'
                invalid_signature:
                  value:
                    errorType: invalid_signature
                    errorMessage: Failed to sign user operation.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user Smart Account with the given address 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: Max concurrent user operations reached.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/solana/sign/message:
    post:
      x-audience: public
      summary: Sign Base64-encoded message
      description: |-
        Signs an arbitrary Base64 encoded message with the given Solana account.
        **WARNING:**  Never sign a message that you didn't generate as it may put your funds at risk.
      operationId: signSolanaMessageWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: userId
          description: The ID of the end user.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The base58 encoded address of the Solana account belonging to the end user.
                  example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                message:
                  type: string
                  description: The base64 encoded arbitrary message to sign.
                  example: SGVsbG8sIHdvcmxk
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - address
                - message
      responses:
        '200':
          description: Successfully signed message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the message, as a base58 encoded string.
                    example: 4YecmNqVT9QFqzuSvE9Zih3toZzNAijjXpj8xupgcC6E4VzwzFjuZBk5P99yz9JQaLRLm1K4L4FpMjxByFxQBe2h
                required:
                  - signature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: invalid_request
                    errorMessage: Malformed message to sign.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Solana account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/solana/sign/transaction:
    post:
      x-audience: public
      summary: Sign transaction via end user Solana account
      description: |-
        Signs a transaction with the given end user Solana account.
        The unsigned transaction should be serialized into a byte array and then encoded as base64.
        **Transaction types**
        The following transaction types are supported:
        * [Legacy transactions](https://solana-labs.github.io/solana-web3.js/classes/Transaction.html)
        * [Versioned transactions](https://solana-labs.github.io/solana-web3.js/classes/VersionedTransaction.html)
        The developer is responsible for ensuring that the unsigned transaction is valid, as the API will not validate the transaction.
      operationId: signSolanaTransactionWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The base58 encoded address of the Solana account belonging to the end user.
                  example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                transaction:
                  type: string
                  description: The base64 encoded transaction to sign.
                  example: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - address
                - transaction
      responses:
        '200':
          description: Successfully signed transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signedTransaction:
                    type: string
                    description: The base64 encoded signed transaction.
                    example: AQACAdSOvpk0UJXs/rQRXYKSI9hcR0bkGp24qGv6t0/M1XjcQpHf6AHwLcPjEtKQI7p/U0Zo98lnJ5/PZMfVq/0BAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                required:
                  - signedTransaction
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user with the given ID not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/solana/sign/x402-payment:
    post:
      x-audience: public
      summary: Sign x402 payment via end user Solana account
      description: |-
        Signs an x402 payment payload using the end user's given Solana account.
        Accepts the full x402 payment required response body from a resource server plus an index into the accepts array selecting which payment option to sign. The paymentRequired envelope's x402Version, resource, and extensions are carried through into the signed payment payload; only the selected accept entry becomes paymentPayload.accepted.
        Returns a signed payment payload that can be base64-encoded and sent in the PAYMENT-SIGNATURE header of the resource request.
        If acceptsIndex is out of range for paymentRequired.accepts, or the selected accept is not a Solana network payment option, the request fails with 422.
      operationId: signSolanaX402PaymentWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XDeveloperAuth'
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentRequired:
                  allOf:
                    - $ref: '#/components/schemas/x402PaymentRequired'
                  description: The complete x402 payment required response body from the resource server. Top-level fields (x402Version, resource, error, extensions) are preserved in the signed payment payload; acceptsIndex selects which entry from accepts is signed as paymentPayload.accepted.
                acceptsIndex:
                  type: integer
                  minimum: 0
                  description: Zero-based index into paymentRequired.accepts selecting which payment option to sign. Must be less than the length of accepts. The entry at this index must be a Solana network payment option for this endpoint.
                  example: 0
                address:
                  type: string
                  description: The base58 encoded address of the end user's Solana account to sign with.
                  example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                walletSecretId:
                  type: string
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
              required:
                - paymentRequired
                - acceptsIndex
                - address
            examples:
              mainnet_solana:
                summary: Mainnet Solana USDC payment, first accept option
                value:
                  paymentRequired:
                    x402Version: 2
                    resource:
                      url: https://api.example.com/premium/resource/123
                      description: Premium API access for data analysis.
                      mimeType: application/json
                    accepts:
                      - scheme: exact
                        network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
                        amount: '1000000'
                        asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                        payTo: 2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
                        maxTimeoutSeconds: 60
                  acceptsIndex: 0
                  address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
              mainnet_base:
                summary: Resource accepting both Base and Solana USDC; pick Solana entry at index 1
                value:
                  paymentRequired:
                    x402Version: 2
                    resource:
                      url: https://api.example.com/premium/resource/123
                      description: Premium API access for data analysis.
                      mimeType: application/json
                    accepts:
                      - scheme: exact
                        network: eip155:8453
                        amount: '1000000'
                        asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                        payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        maxTimeoutSeconds: 60
                      - scheme: exact
                        network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
                        amount: '1000000'
                        asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                        payTo: 2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
                        maxTimeoutSeconds: 60
                  acceptsIndex: 1
                  address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
      responses:
        '200':
          description: Successfully signed x402 payment payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paymentPayload:
                    allOf:
                      - $ref: '#/components/schemas/x402PaymentPayload'
                    description: The signed x402 payment payload. Base64-encode this and send it in the PAYMENT-SIGNATURE header of the resource request.
                required:
                  - paymentPayload
              examples:
                signed_solana_payload:
                  summary: Signed Solana x402 payment payload
                  value:
                    paymentPayload:
                      x402Version: 2
                      accepted:
                        scheme: exact
                        network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
                        amount: '1000000'
                        asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                        payTo: 2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
                        maxTimeoutSeconds: 60
                      payload:
                        transaction: AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAED
                signed_solana_from_multi_network_payload:
                  summary: Signed Solana payload when resource server also accepts Base (index 1 selected)
                  value:
                    paymentPayload:
                      x402Version: 2
                      accepted:
                        scheme: exact
                        network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
                        amount: '1000000'
                        asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                        payTo: 2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
                        maxTimeoutSeconds: 60
                      payload:
                        transaction: AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAED
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Request body must be specified.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Solana account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          description: Semantically invalid request. The idempotency key was reused with a different payload, acceptsIndex is out of range for paymentRequired.accepts, or the selected accept is not a Solana network payment option.
          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.
                accepts_index_out_of_bounds:
                  value:
                    errorType: invalid_request
                    errorMessage: acceptsIndex is out of range for paymentRequired.accepts.
                non_solana_accept:
                  value:
                    errorType: invalid_request
                    errorMessage: The payment option at acceptsIndex must be a Solana network accept.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/solana/send/transaction:
    post:
      x-audience: public
      summary: Send transaction via end user Solana account
      description: |-
        Signs a transaction with the given end user Solana account and sends it to the indicated supported network.
        The API handles recent blockhash management and fee estimation, leaving the developer to provide only the minimal set of fields necessary to send the transaction.
        The unsigned transaction should be serialized into a byte array and then encoded as base64.
        **Transaction types**
        The following transaction types are supported:
        * [Legacy transactions](https://solana.com/developers/guides/advanced/versions#current-transaction-versions)
        * [Versioned transactions](https://solana.com/developers/guides/advanced/versions)
        **Instruction Batching**
        To batch multiple operations, include multiple instructions within a single transaction. All instructions within a transaction are executed atomically - if any instruction fails, the entire transaction fails and is rolled back.
        **Network Support**
        The following Solana networks are supported:
        * `solana` - Solana Mainnet
        * `solana-devnet` - Solana Devnet
        The developer is responsible for ensuring that the unsigned transaction is valid, as the API will not validate the transaction.
      operationId: sendSolanaTransactionWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XDeveloperAuth'
        - name: userId
          description: The ID of the end user.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
            example: e051beeb-7163-4527-a5b6-35e301529ff2
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The base58 encoded address of the Solana account belonging to the end user.
                  example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                network:
                  type: string
                  description: The Solana network to send the transaction to.
                  enum:
                    - solana
                    - solana-devnet
                  example: solana-devnet
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
                transaction:
                  type: string
                  description: The base64 encoded transaction to sign and send. This transaction can contain multiple instructions for native Solana batching.
                  example: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                useCdpSponsor:
                  type: boolean
                  description: Whether transaction fees should be sponsored by CDP. When true, CDP sponsors the transaction fees on behalf of the end user. When false, the end user is responsible for paying the transaction fees.
                  example: true
              required:
                - address
                - network
                - transaction
            examples:
              send_transaction:
                summary: Send a transaction
                value:
                  address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  network: solana-devnet
                  transaction: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
              send_transaction_sponsored:
                summary: Send a transaction with CDP gas sponsorship
                value:
                  address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  network: solana-devnet
                  transaction: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
                  useCdpSponsor: true
      responses:
        '200':
          description: Successfully signed and sent transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionSignature:
                    type: string
                    description: The base58 encoded transaction signature.
                    example: 5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
                required:
                  - transactionSignature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/embedded-wallet-api/end-users/{userId}/solana/{address}/send/{asset}:
    post:
      x-audience: public
      summary: Send USDC on Solana
      description: |-
        Sends USDC from an end user's Solana account to a recipient address on the Solana network. This endpoint simplifies USDC transfers by automatically handling mint resolution, Associated Token Account (ATA) creation, decimal conversion, and transaction encoding.
        The `amount` field accepts human-readable amounts as decimal strings (e.g., "1.5", "25.50").
        Use the optional `createRecipientAta` parameter to control whether the sender pays for creating the recipient's Associated Token Account if it doesn't exist.
      operationId: sendSolanaAssetWithEndUserAccount
      tags:
        - End User Accounts
      security:
        - endUserAuth: []
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuthOptional'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XDeveloperAuth'
        - name: userId
          in: path
          required: true
          description: The ID of the end user.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9-]{1,100}$
          example: e051beeb-7163-4527-a5b6-35e301529ff2
        - name: address
          description: The base58 encoded address of the Solana account to send USDC from.
          in: path
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/BlockchainAddress'
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        - name: asset
          in: path
          required: true
          description: The asset to send. Currently only "usdc" is supported.
          schema:
            allOf:
              - $ref: '#/components/schemas/Asset'
            enum:
              - usdc
          example: usdc
        - $ref: '#/components/parameters/ProjectIDOptional'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  allOf:
                    - $ref: '#/components/schemas/BlockchainAddress'
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                  description: The base58 encoded address of the recipient.
                  example: ExXhNkgYf6efh7YyqDRVxPZuzafobao1A74drUdp8trd
                amount:
                  type: string
                  minLength: 1
                  maxLength: 32
                  description: The amount of USDC to send as a decimal string (e.g., "1.5" or "25.50").
                  example: '1.50'
                network:
                  type: string
                  description: The Solana network to send USDC on.
                  enum:
                    - solana
                    - solana-devnet
                  example: solana-devnet
                createRecipientAta:
                  type: boolean
                  description: Whether to automatically create an Associated Token Account (ATA) for the recipient if it doesn't exist. When true, the sender pays the rent-exempt minimum to create the recipient's USDC ATA. When false, the transaction will fail if the recipient doesn't have a USDC ATA.
                  example: true
                walletSecretId:
                  description: Required when not using delegated signing. The ID of the Temporary Wallet Secret that was used to sign the X-Wallet-Auth Header.
                  type: string
                  pattern: ^[a-zA-Z0-9-]{1,100}$
                  example: e051beeb-7163-4527-a5b6-35e301529ff2
                useCdpSponsor:
                  type: boolean
                  description: Whether transaction fees should be sponsored by CDP. When true, CDP sponsors the transaction fees on behalf of the end user. When false, the end user is responsible for paying the transaction fees.
                  example: true
              required:
                - to
                - amount
                - network
            examples:
              send_usdc_auto_create_ata:
                summary: Send USDC (auto-create ATA)
                value:
                  to: ExXhNkgYf6efh7YyqDRVxPZuzafobao1A74drUdp8trd
                  amount: '25.50'
                  network: solana-devnet
                  createRecipientAta: true
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
              send_usdc_no_ata_creation:
                summary: Send USDC (no ATA creation)
                value:
                  to: ExXhNkgYf6efh7YyqDRVxPZuzafobao1A74drUdp8trd
                  amount: '5.00'
                  network: solana-devnet
                  createRecipientAta: false
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
              send_usdc_sponsored:
                summary: Send USDC with CDP gas sponsorship
                value:
                  to: ExXhNkgYf6efh7YyqDRVxPZuzafobao1A74drUdp8trd
                  amount: '25.50'
                  network: solana-devnet
                  walletSecretId: e051beeb-7163-4527-a5b6-35e301529ff2
                  useCdpSponsor: true
      responses:
        '200':
          description: Successfully sent transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionSignature:
                    type: string
                    description: The base58 encoded transaction signature.
                    example: 5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
                required:
                  - transactionSignature
              examples:
                successful_transfer:
                  value:
                    transactionSignature: 5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_amount:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid amount format. Amount must be a valid decimal string.
                    errorParam: amount
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                invalid_network:
                  value:
                    errorType: invalid_request
                    errorMessage: Unsupported network for USDC transfers.
                    errorParam: network
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                invalid_asset:
                  value:
                    errorType: invalid_request
                    errorMessage: Unsupported asset. Currently only 'usdc' is supported.
                    errorParam: asset
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                insufficient_balance:
                  value:
                    errorType: invalid_request
                    errorMessage: Account has insufficient USDC balance to complete the transfer.
                    errorParam: amount
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                insufficient_sol:
                  value:
                    errorType: invalid_request
                    errorMessage: Account has insufficient SOL to pay for transaction fees and rent.
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                recipient_ata_missing:
                  value:
                    errorType: invalid_request
                    errorMessage: 'Recipient does not have a USDC Associated Token Account. Set ''createRecipientAta: true'' to create one automatically.'
                    errorParam: to
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          $ref: '#/components/responses/DelegationForbiddenError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts:
    get:
      x-audience: public
      summary: List EVM accounts
      description: |-
        Lists the EVM accounts belonging to the developer's CDP Project.
        The response is paginated, and by default, returns 20 accounts per page.
      operationId: listEvmAccounts
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully listed EVM accounts.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/EvmAccount'
                        description: The list of EVM accounts.
                    required:
                      - accounts
                  - $ref: '#/components/schemas/ListResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      x-audience: public
      summary: Create EVM account
      description: Creates a new EVM account.
      operationId: createEvmAccount
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: |-
                    An optional name for the account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all EVM accounts in the developer's CDP Project.
                  example: my-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
                accountPolicy:
                  type: string
                  x-audience: public
                  description: The ID of the account-level policy to apply to the account.
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '201':
          description: Successfully created EVM account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Project has no secret. Please register a secret with the project.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '409':
          description: Resource already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_exists:
                  value:
                    errorType: already_exists
                    errorMessage: EVM account with the given name already exists.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}:
    get:
      x-audience: public
      summary: Get EVM account by address
      description: Gets an EVM account by its address.
      operationId: getEvmAccount
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The 0x-prefixed address of the EVM account. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      responses:
        '200':
          description: Successfully got EVM account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "name": string doesn''t match the regular expression "^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$".'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      x-audience: public
      summary: Update EVM account
      description: Updates an existing EVM account. Use this to update the account's name or account-level policy.
      operationId: updateEvmAccount
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: |-
                    An optional name for the account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all EVM accounts in the developer's CDP Project.
                  example: my-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
                accountPolicy:
                  type: string
                  x-audience: public
                  description: The ID of the account-level policy to apply to the account, or an empty string to unset attached policy.
                  pattern: (^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^$)
                  example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Successfully updated EVM account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "/name": string doesn''t match the regular expression  "^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$".'
        '404':
          description: EVM account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/by-name/{name}:
    get:
      x-audience: public
      summary: Get EVM account by name
      description: Gets an EVM account by its name.
      operationId: getEvmAccountByName
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: name
          description: The name of the EVM account.
          in: path
          required: true
          schema:
            type: string
          example: my-account
      responses:
        '200':
          description: Successfully got EVM account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'error: parameter "name" must be a string.'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given name not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/send/transaction:
    post:
      x-audience: public
      summary: Send transaction
      description: |-
        Signs a transaction with the given EVM account and sends it to the indicated supported network. This API handles nonce management and gas estimation, leaving the developer to provide only the minimal set of fields necessary to send the transaction. The transaction should be serialized as a hex string using [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/).

        The transaction must be an [EIP-1559 dynamic fee transaction](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md).


        **Transaction fields and API behavior**

        - `to` *(Required)*: The address of the contract or account to send the transaction to.
        - `chainId` *(Ignored)*: The value of the `chainId` field in the transaction is ignored.
          The transaction will be sent to the network indicated by the `network` field in the request body.

        - `nonce` *(Optional)*: The nonce to use for the transaction. If not provided, the API will assign
           a nonce to the transaction based on the current state of the account.

        - `maxPriorityFeePerGas` *(Optional)*: The maximum priority fee per gas to use for the transaction.
           If not provided, the API will estimate a value based on current network conditions.

        - `maxFeePerGas` *(Optional)*: The maximum fee per gas to use for the transaction.
           If not provided, the API will estimate a value based on current network conditions.

        - `gasLimit` *(Optional)*: The gas limit to use for the transaction. If not provided, the API will estimate a value
          based on the `to` and `data` fields of the transaction.

        - `value` *(Optional)*: The amount of ETH, in wei, to send with the transaction.
        - `data` *(Optional)*: The data to send with the transaction; only used for contract calls.
        - `accessList` *(Optional)*: The access list to use for the transaction.
      operationId: sendEvmTransaction
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the Ethereum account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  type: string
                  description: The network to send the transaction to.
                  enum:
                    - base
                    - base-sepolia
                    - ethereum
                    - ethereum-sepolia
                    - avalanche
                    - polygon
                    - optimism
                    - arbitrum
                    - arbitrum-sepolia
                    - world
                    - world-sepolia
                  example: base-sepolia
                transaction:
                  type: string
                  description: The RLP-encoded transaction to sign and send, as a 0x-prefixed hex string.
                  example: '0xf86b098505d21dba00830334509431415daf58e2c6b7323b4c58712fd92952145da79018080'
              required:
                - transaction
                - network
      responses:
        '200':
          description: Successfully signed and sent transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionHash:
                    type: string
                    description: The hash of the transaction, as a 0x-prefixed hex string.
                    example: '0xf8f98fb6726fc936f24b2007df5cb20e2b8444ff3dfaa2a929335f432a9be2e7'
                required:
                  - transactionHash
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/sign/transaction:
    post:
      x-audience: public
      summary: Sign transaction
      description: |-
        Signs a transaction with the given EVM account.
        The transaction should be serialized as a hex string using [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/).

        The transaction must be an [EIP-1559 dynamic fee transaction](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md). The developer is responsible for ensuring that the unsigned transaction is valid, as the API will not validate the transaction.
      operationId: signEvmTransaction
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction:
                  type: string
                  description: The RLP-encoded transaction to sign, as a 0x-prefixed hex string.
                  example: '0xf86b098505d21dba00830334509431415daf58e2c6b7323b4c58712fd92952145da79018080'
              required:
                - transaction
      responses:
        '200':
          description: Successfully signed transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signedTransaction:
                    type: string
                    description: The RLP-encoded signed transaction, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signedTransaction
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/sign:
    post:
      x-audience: public
      summary: Sign hash
      description: Signs an arbitrary 32 byte hash with the given EVM account.
      operationId: signEvmHash
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hash:
                  type: string
                  description: The arbitrary 32 byte hash to sign.
                  example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
              required:
                - hash
      responses:
        '200':
          description: Successfully signed hash.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the hash, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Request body must be specified.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/sign/message:
    post:
      x-audience: public
      summary: Sign EIP-191 message
      description: |-
        Signs an [EIP-191](https://eips.ethereum.org/EIPS/eip-191) message with the given EVM account.

        Per the specification, the message in the request body is prepended with `0x19 <0x45 (E)> <thereum Signed Message:\n" + len(message)>` before being signed.
      operationId: signEvmMessage
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The message to sign.
                  example: Hello, world!
              required:
                - message
      responses:
        '200':
          description: Successfully signed message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the message, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signature
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/sign/typed-data:
    post:
      x-audience: public
      summary: Sign EIP-712 typed data
      description: Signs [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data with the given EVM account.
      operationId: signEvmTypedData
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EIP712Message'
      responses:
        '200':
          description: Successfully signed typed data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the typed data, as a 0x-prefixed hex string.
                    example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
                required:
                  - signature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/eip7702/delegation:
    post:
      x-audience: public
      summary: Create EIP-7702 delegation
      description: |-
        Creates an EIP-7702 delegation for an EVM EOA account, upgrading it with smart account capabilities.

        This endpoint:
        - Retrieves delegation artifacts from onchain
        - Signs the EIP-7702 authorization for delegation
        - Assembles and submits a Type 4 transaction
        - Creates an associated smart account object

        The delegation allows the EVM EOA to be used as a smart account, which enables batched transactions and gas sponsorship via paymaster.
      operationId: createEvmEip7702Delegation
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account to delegate.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  $ref: '#/components/schemas/EvmEip7702DelegationNetwork'
                enableSpendPermissions:
                  type: boolean
                  description: Whether to configure spend permissions for the upgraded, delegated account. When enabled, the account can grant permissions for third parties to spend on its behalf.
                  example: true
              required:
                - network
      responses:
        '201':
          description: Delegation operation created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  delegationOperationId:
                    type: string
                    format: uuid
                    description: The unique identifier for the delegation operation. Use this to poll the operation status.
                    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                required:
                  - delegationOperationId
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_network:
                  value:
                    errorType: invalid_request
                    errorMessage: Field 'network' is required.
                    errorParam: network
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
                unsupported_network:
                  value:
                    errorType: invalid_request
                    errorMessage: Network 'gnosis' is not supported for EIP-7702.
                    errorParam: network
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: EVM account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '409':
          description: Account already delegated on the given network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_delegated:
                  value:
                    errorType: already_exists
                    errorMessage: Account already has an active EIP-7702 delegation on the given network.
                    errorParam: address
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#already-exists
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/eip7702/delegation-operations/{delegationOperationId}:
    get:
      x-audience: public
      summary: Get EIP-7702 delegation operation by ID
      description: Returns the EIP-7702 delegation operation. Use the delegationOperationId returned by the Create EIP-7702 delegation endpoint to poll for operation completion.
      operationId: getEvmEip7702DelegationOperationById
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: delegationOperationId
          description: The unique identifier for the delegation operation.
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: ^[a-f0-9\-]{36}$
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Delegation operation retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmEip7702DelegationOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_id:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid delegation operation ID format.
                    errorParam: delegationOperationId
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#invalid-request
        '404':
          description: Delegation operation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Delegation operation not found.
                    errorParam: delegationOperationId
                    errorLink: https://docs.cdp.coinbase.com/api-reference/v2/errors#not-found
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts:
    get:
      summary: List Smart Accounts
      description: |-
        Lists the Smart Accounts belonging to the developer's CDP Project.
        The response is paginated, and by default, returns 20 accounts per page.
      operationId: listEvmSmartAccounts
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully listed Smart Accounts.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/EvmSmartAccount'
                        description: The list of Smart Accounts.
                    required:
                      - accounts
                  - $ref: '#/components/schemas/ListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      summary: Create Smart Account
      description: Creates a new Smart Account.
      operationId: createEvmSmartAccount
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                owners:
                  type: array
                  description: Today, only a single owner can be set for a Smart Account, but this is an array to allow setting multiple owners in the future.
                  items:
                    type: string
                    pattern: ^0x[0-9a-fA-F]{40}$
                  example:
                    - '0xfc807D1bE4997e5C7B33E4d8D57e60c5b0f02B1a'
                name:
                  type: string
                  description: |-
                    An optional name for the account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all EVM accounts in the developer's CDP Project.
                  example: my-smart-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
              required:
                - owners
      responses:
        '201':
          description: Successfully created Smart Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSmartAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid owner address or account name provided.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/by-name/{name}:
    get:
      x-audience: public
      summary: Get Smart Account by name
      description: Gets a Smart Account by its name.
      operationId: getEvmSmartAccountByName
      security:
        - apiKeyAuth: []
      tags:
        - EVM Smart Accounts
      parameters:
        - name: name
          description: The name of the Smart Account.
          in: path
          required: true
          schema:
            type: string
          example: my-account
      responses:
        '200':
          description: Successfully got Smart Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSmartAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'error: parameter "name" must be a string.'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Smart Account with the given name not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/import:
    post:
      x-audience: public
      summary: Import EVM account
      description: Import an existing EVM account into the developer's CDP Project. This API should be called from the [CDP SDK](https://github.com/coinbase/cdp-sdk) to ensure that the associated private key is properly encrypted.
      operationId: importEvmAccount
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                encryptedPrivateKey:
                  type: string
                  description: The base64-encoded, encrypted private key of the EVM account. The private key must be encrypted using the CDP SDK's encryption scheme.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                name:
                  type: string
                  description: |-
                    An optional name for the account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all EVM accounts in the developer's CDP Project.
                  example: my-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
                accountPolicy:
                  type: string
                  x-audience: public
                  description: The ID of the account-level policy to apply to the account.
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  example: 123e4567-e89b-12d3-a456-426614174000
              required:
                - encryptedPrivateKey
      responses:
        '201':
          description: Successfully imported EVM account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: The encrypted private key is invalid.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '409':
          description: Resource already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_exists:
                  value:
                    errorType: already_exists
                    errorMessage: EVM account with the given address already exists.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/{address}/export:
    post:
      x-audience: public
      summary: Export EVM account
      description: Export an existing EVM account's private key. It is important to store the private key in a secure place after it's exported.
      operationId: exportEvmAccount
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - accounts#export
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The 0x-prefixed address of the EVM account. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                exportEncryptionKey:
                  type: string
                  description: The base64-encoded, public part of the RSA key in DER format used to encrypt the account private key.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
              required:
                - exportEncryptionKey
      responses:
        '200':
          description: Successfully exported EVM account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  encryptedPrivateKey:
                    type: string
                    description: The base64-encoded, encrypted private key of the EVM account which is a 32 byte raw private key. The private key is encrypted in transport using the exportEncryptionKey in the request.
                    example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                required:
                  - encryptedPrivateKey
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: EVM account with the given address not found.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given address not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/accounts/export/by-name/{name}:
    post:
      x-audience: public
      summary: Export EVM account by name
      description: Export an existing EVM account's private key by its name. It is important to store the private key in a secure place after it's exported.
      operationId: exportEvmAccountByName
      tags:
        - EVM Accounts
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - accounts#export
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: name
          description: The name of the EVM account.
          in: path
          required: true
          schema:
            type: string
          example: my-account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                exportEncryptionKey:
                  type: string
                  description: The base64-encoded, public part of the RSA key in DER format used to encrypt the account private key.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
              required:
                - exportEncryptionKey
      responses:
        '200':
          description: Successfully exported EVM account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  encryptedPrivateKey:
                    type: string
                    description: The base64-encoded, encrypted private key of the EVM account which is a 32 byte raw private key. The private key is encrypted in transport using the exportEncryptionKey in the request.
                    example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                required:
                  - encryptedPrivateKey
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'error: parameter "name" must be a string.'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM account with the given name not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}:
    get:
      summary: Get Smart Account by address
      description: Gets a Smart Account by its address.
      operationId: getEvmSmartAccount
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The 0x-prefixed address of the Smart Account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      responses:
        '200':
          description: Successfully got Smart Account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSmartAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid address provided.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Smart Account with the given address not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      x-audience: public
      summary: Update EVM Smart Account
      description: Updates an existing EVM smart account. Use this to update the smart account's name.
      operationId: updateEvmSmartAccount
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The 0x-prefixed address of the EVM smart account. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: |-
                    An optional name for the smart account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all EVM smart accounts in the developer's CDP Project.
                  example: my-smart-account
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
      responses:
        '200':
          description: Successfully updated EVM smart account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmSmartAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "/name": string doesn''t match the regular expression  "^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$".'
        '404':
          description: EVM account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM smart account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/user-operations:
    post:
      summary: Prepare user operation
      description: Prepares a new user operation on a Smart Account for a specific network.
      operationId: prepareUserOperation
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The address of the Smart Account to create the user operation on.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  $ref: '#/components/schemas/EvmUserOperationNetwork'
                calls:
                  type: array
                  description: The list of calls to make from the Smart Account.
                  items:
                    $ref: '#/components/schemas/EvmCall'
                paymasterUrl:
                  allOf:
                    - $ref: '#/components/schemas/Url'
                  description: The URL of the paymaster to use for the user operation.
                  example: https://api.developer.coinbase.com/rpc/v1/base/<token>
                paymasterContext:
                  $ref: '#/components/schemas/PaymasterContext'
                dataSuffix:
                  type: string
                  pattern: ^0x[0-9a-fA-F]+$
                  description: The EIP-8021 data suffix (hex-encoded) that enables transaction attribution for the user operation.
                  example: '0xdddddddd62617365617070070080218021802180218021802180218021'
              required:
                - network
                - calls
      responses:
        '201':
          description: The prepared user operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Field "network" is required.
                paymaster_context_without_paymaster:
                  value:
                    errorType: invalid_request
                    errorMessage: 'paymasterContext requires a paymaster: set paymasterUrl.'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: EVM smart account with the given address not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/user-operations/prepare-and-send:
    post:
      x-audience: public
      summary: Prepare and send user operation
      description: Prepares, signs, and sends a user operation for an EVM Smart Account. This API can be used only if the owner on Smart Account is a CDP EVM Account.
      operationId: prepareAndSendUserOperation
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XWalletAuth'
        - name: address
          description: The address of the EVM Smart Account to execute the user operation from.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  $ref: '#/components/schemas/EvmUserOperationNetwork'
                calls:
                  type: array
                  description: The list of calls to make from the Smart Account.
                  items:
                    $ref: '#/components/schemas/EvmCall'
                paymasterUrl:
                  allOf:
                    - $ref: '#/components/schemas/Url'
                  description: The URL of the paymaster to use for the user operation.
                  example: https://api.developer.coinbase.com/rpc/v1/base/<token>
                paymasterContext:
                  $ref: '#/components/schemas/PaymasterContext'
              required:
                - network
                - calls
      responses:
        '200':
          description: The user operation was successfully prepared, signed, and sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Field "network" is required.
                paymaster_context_without_paymaster:
                  value:
                    errorType: invalid_request
                    errorMessage: 'paymasterContext requires a paymaster: set paymasterUrl.'
                invalid_signature:
                  value:
                    errorType: invalid_signature
                    errorMessage: Failed to sign user operation.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: End user Smart Account with the given address 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: Max concurrent user operations reached.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/user-operations/{userOpHash}:
    get:
      summary: Get user operation
      description: Gets a user operation by its hash.
      operationId: getUserOperation
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The address of the Smart Account the user operation belongs to.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: userOpHash
          description: The hash of the user operation to fetch.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{64}$
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
      responses:
        '200':
          description: Successfully retrieved the user operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: User operation not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/user-operations/{userOpHash}/send:
    post:
      summary: Send user operation
      description: |-
        Sends a user operation with a signature.
        The payload to sign must be the `userOpHash` field of the user operation. This hash should be signed directly (not using `personal_sign` or EIP-191 message hashing).
        The signature must be 65 bytes in length, consisting of: - 32 bytes for the `r` value - 32 bytes for the `s` value - 1 byte for the `v` value (must be 27 or 28)
        If using the CDP Paymaster, the user operation must be signed and sent within 2 minutes of being prepared.
      operationId: sendUserOperation
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The address of the Smart Account to send the user operation from.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: userOpHash
          description: The hash of the user operation to send.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{64}$
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  type: string
                  description: The hex-encoded signature of the user operation. This should be a 65-byte signature consisting of the `r`, `s`, and `v` values of the ECDSA signature. Note that the `v` value should conform to the `personal_sign` standard, which means it should be 27 or 28.
                  example: '0x1b0c9cf8cd4554c6c6d9e7311e88f1be075d7f25b418a044f4bf2c0a42a93e212ad0a8b54de9e0b5f7e3812de3f2c6cc79aa8c3e1c02e7ad14b4a8f42012c2c01b'
              required:
                - signature
      responses:
        '200':
          description: The sent user operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_signature:
                  value:
                    errorType: invalid_signature
                    errorMessage: Invalid signature.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: User operation 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: Max concurrent user operations reached.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/spend-permissions:
    post:
      x-audience: public
      summary: Create spend permission
      description: Creates a spend permission for the given smart account address.
      operationId: createSpendPermission
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The address of the Smart Account to create the spend permission for.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpendPermissionRequest'
      responses:
        '200':
          description: Successfully created spend permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Smart account not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/spend-permissions/list:
    get:
      x-audience: public
      summary: List spend permissions
      description: Lists spend permission for the given smart account address.
      operationId: listSpendPermissions
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The address of the Smart account to list spend permissions for.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: pageSize
          description: The number of spend permissions to return per page.
          in: query
          required: false
          schema:
            type: integer
            default: 20
          example: 10
        - name: pageToken
          description: The token for the next page of spend permissions. Will be empty if there are no more spend permissions to fetch.
          in: query
          required: false
          schema:
            type: string
          example: eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ==
      responses:
        '200':
          description: Successfully listed spend permissions.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - spendPermissions
                    properties:
                      spendPermissions:
                        type: array
                        description: The spend permissions for the smart account.
                        items:
                          $ref: '#/components/schemas/SpendPermissionResponseObject'
                  - $ref: '#/components/schemas/ListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Smart account not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/smart-accounts/{address}/spend-permissions/revoke:
    post:
      x-audience: public
      summary: Revoke spend permission
      description: Revokes an existing spend permission.
      operationId: revokeSpendPermission
      tags:
        - EVM Smart Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The address of the Smart account this spend permission is valid for.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeSpendPermissionRequest'
      responses:
        '200':
          description: Successfully revoked spend permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvmUserOperation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Smart account not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/swaps/quote:
    get:
      x-audience: public
      summary: Get swap price estimate
      description: Get a price estimate for a swap between two tokens on an EVM network.
      operationId: getEvmSwapPrice
      tags:
        - EVM Swaps
      security:
        - apiKeyAuth: []
      parameters:
        - in: query
          name: network
          required: true
          schema:
            $ref: '#/components/schemas/EvmSwapsNetwork'
        - in: query
          name: toToken
          required: true
          schema:
            $ref: '#/components/schemas/toToken'
        - in: query
          name: fromToken
          required: true
          schema:
            $ref: '#/components/schemas/fromToken'
        - in: query
          name: fromAmount
          required: true
          schema:
            $ref: '#/components/schemas/fromAmount'
        - in: query
          name: taker
          required: true
          schema:
            $ref: '#/components/schemas/taker'
        - in: query
          name: signerAddress
          required: false
          schema:
            $ref: '#/components/schemas/signerAddress'
        - in: query
          name: gasPrice
          required: false
          schema:
            $ref: '#/components/schemas/gasPrice'
        - in: query
          name: slippageBps
          required: false
          schema:
            $ref: '#/components/schemas/slippageBps'
      responses:
        '200':
          description: A price estimate for the swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSwapPriceResponseWrapper'
              examples:
                success:
                  summary: Successful swap price retrieval
                  value:
                    blockNumber: '17038723'
                    toAmount: '1000000000000000000'
                    toToken: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607'
                    fees:
                      gasFee:
                        amount: '1000000000000000000'
                        token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
                      protocolFee:
                        amount: '1000000000000000000'
                        token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
                    issues:
                      allowance:
                        currentAllowance: '1000000000'
                        spender: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
                      balance:
                        token: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                        currentBalance: '1000000000000000000'
                        requiredBalance: '1000000000000000000'
                      simulationIncomplete: false
                    liquidityAvailable: true
                    minToAmount: '900000000000000000'
                    fromAmount: '1000000000000000000'
                    fromToken: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                    gas: '100000'
                    gasPrice: '1000000000'
                unavailable:
                  summary: Swap with unavailable liquidity
                  value:
                    liquidityAvailable: false
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '403':
          description: Taker not permitted to perform swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Taker not permitted to perform swap.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/swaps:
    post:
      x-audience: public
      summary: Create swap quote
      description: Create a swap quote, which includes the payload to sign as well as the transaction data needed to execute the swap. The developer is responsible for signing the payload and submitting the transaction to the network in order to execute the swap.
      operationId: createEvmSwapQuote
      tags:
        - EVM Swaps
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  $ref: '#/components/schemas/EvmSwapsNetwork'
                toToken:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                  description: The 0x-prefixed contract address of the token to receive.
                  example: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607'
                fromToken:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                  description: The 0x-prefixed contract address of the token to send.
                  example: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                fromAmount:
                  type: string
                  pattern: ^\d+$
                  description: The amount of the `fromToken` to send in atomic units of the token. For example, `1000000000000000000` when sending ETH equates to 1 ETH, `1000000` when sending USDC equates to 1 USDC, etc.
                  example: '1000000000000000000'
                taker:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                  description: The 0x-prefixed address that holds the `fromToken` balance and has the `Permit2` allowance set for the swap.
                  example: '0xAc0974bec39a17e36ba4a6b4d238ff944bacb478'
                signerAddress:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                  description: The 0x-prefixed Externally Owned Account (EOA) address that will sign the `Permit2` EIP-712 permit message. This is only needed if `taker` is a smart contract.
                  example: '0x922f49447d8a07e3bd95bd0d56f35241523fbab8'
                gasPrice:
                  type: string
                  pattern: ^\d+$
                  description: The target gas price for the swap transaction, in Wei. For EIP-1559 transactions, this value should be seen as the `maxFeePerGas` value. If not provided, the API will use an estimate based on the current network conditions.
                  example: '1000000000'
                slippageBps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                  description: The maximum acceptable slippage of the `toToken` in basis points. If this parameter is set to 0, no slippage will be tolerated. If not provided, the default slippage tolerance is 100 bps (i.e., 1%).
                  default: 100
                  example: 100
              required:
                - network
                - toToken
                - fromToken
                - fromAmount
                - taker
      responses:
        '201':
          description: Successfully created swap quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSwapQuoteResponseWrapper'
              examples:
                success:
                  summary: Successful swap quote creation
                  value:
                    blockNumber: '17038723'
                    toAmount: '1000000000000000000'
                    toToken: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607'
                    fees:
                      gasFee:
                        amount: '1000000000000000000'
                        token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
                      protocolFee:
                        amount: '1000000000000000000'
                        token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
                    issues:
                      allowance:
                        currentAllowance: '1000000000'
                        spender: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
                      balance:
                        token: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                        currentBalance: '1000000000000000000'
                        requiredBalance: '1000000000000000000'
                      simulationIncomplete: false
                    liquidityAvailable: true
                    minToAmount: '900000000000000000'
                    fromAmount: '1000000000000000000'
                    fromToken: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
                    permit2:
                      hash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                      eip712:
                        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'
                    transaction:
                      to: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
                      data: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                      gas: '100000'
                      gasPrice: '1000000000'
                      value: '1000000000000000000'
                unavailable:
                  summary: Swap with unavailable liquidity
                  value:
                    liquidityAvailable: false
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request body and parameters.
        '403':
          description: Taker not permitted to perform swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Taker not permitted to perform swap.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/token-balances/{network}/{address}:
    get:
      summary: List EVM token balances
      x-audience: public
      description: |-
        Lists the token balances of an EVM address on a given network. The balances include ERC-20 tokens and the native gas token (usually ETH). The response is paginated, and by default, returns 20 balances per page.

        Calls to the `base` and `base-sepolia` networks offer:
          * 99.5% < 2 second freshness from chain tip for new tokens on an address.
          * 99.5% < 2 second freshness from chain tip for balance data.

        Calls to the `ethereum` network offer:
          * 99% < 30 second freshness from chain tip for new tokens on an address.
          * 99% < 2 second freshness from chain tip for balance data.
      operationId: listEvmTokenBalances
      tags:
        - EVM Token Balances
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The 0x-prefixed EVM address to get balances for. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: network
          description: The human-readable network name to get the balances for.
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ListEvmTokenBalancesNetwork'
          example: base
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully listed token balances.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - balances
                    properties:
                      balances:
                        type: array
                        items:
                          $ref: '#/components/schemas/TokenBalance'
                        description: The list of EVM token balances.
                        example:
                          - amount:
                              amount: '1250000000000000000'
                              decimals: 18
                            token:
                              network: base
                              symbol: ETH
                              name: ether
                              contractAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
                          - amount:
                              amount: '123456'
                              decimals: 6
                            token:
                              network: base
                              symbol: USDC
                              name: USD Coin
                              contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                  - $ref: '#/components/schemas/ListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: string doesn't match the regular expression "^0x[0-9a-fA-F]{40}$".
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Address not found, or no balances found for the given address on this chain.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/evm/faucet:
    post:
      x-audience: public
      summary: Request funds on EVM test networks
      description: |
        Request funds from the CDP Faucet on supported EVM test networks.

        Faucets are available for ETH, USDC, EURC, and cbBTC on Base Sepolia and Ethereum Sepolia, and for ETH only on Ethereum Hoodi.

        To prevent abuse, we enforce rate limits within a rolling 24-hour window to control the amount of funds that can be requested.
        These limits are applied at both the CDP User level and the blockchain address level.
        A single blockchain address cannot exceed the specified limits, even if multiple users submit requests to the same address.

        | Token | Amount per Faucet Request |Rolling 24-hour window Rate Limits|
        |:-----:|:-------------------------:|:--------------------------------:|
        | ETH   | 0.0001 ETH                | 0.1 ETH                          |
        | USDC  | 1 USDC                    | 10 USDC                          |
        | EURC  | 1 EURC                    | 10 EURC                          |
        | cbBTC | 0.0001 cbBTC              | 0.001 cbBTC                      |
      operationId: requestEvmFaucet
      tags:
        - Faucets
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  type: string
                  description: The network to request funds from.
                  enum:
                    - base-sepolia
                    - ethereum-sepolia
                    - ethereum-hoodi
                  example: base-sepolia
                address:
                  type: string
                  description: The address to request funds to, which is a 0x-prefixed hexadecimal string.
                  pattern: ^0x[0-9a-fA-F]{40}$
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                token:
                  type: string
                  description: The token to request funds for.
                  enum:
                    - eth
                    - usdc
                    - eurc
                    - cbbtc
                  example: eth
              required:
                - network
                - address
                - token
      responses:
        '200':
          description: Successfully requested funds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionHash:
                    type: string
                    description: |-
                      The hash of the transaction that requested the funds.
                      **Note:** In rare cases, when gas conditions are unusually high, the transaction may not confirm, and the system may issue a replacement transaction to complete the faucet request. In these rare cases, the `transactionHash` will be out of sync with the actual faucet transaction that was confirmed onchain.
                    example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                required:
                  - transactionHash
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "address": string doesn''t match the regular expression "^0x[0-9a-fA-F]{40}$".'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to request faucet funds for this address.
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                faucet_limit_exceeded:
                  value:
                    errorType: faucet_limit_exceeded
                    errorMessage: Faucet limit reached for this address. Please try again later.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/policy-engine/policies:
    get:
      x-audience: public
      summary: List policies
      description: |-
        Lists the policies belonging to the developer's CDP Project. Use the `scope` parameter to filter the policies by scope.
        The response is paginated, and by default, returns 20 policies per page.
      operationId: listPolicies
      tags:
        - Policy Engine
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
        - name: scope
          description: The scope of the policies to return. If `project`, the response will include exactly one policy, which is the project-level policy. If `account`, the response will include all account-level policies for the developer's CDP Project.
          in: query
          required: false
          schema:
            type: string
            enum:
              - project
              - account
          example: project
      responses:
        '200':
          description: Successfully listed policies.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      policies:
                        type: array
                        items:
                          $ref: '#/components/schemas/Policy'
                        description: The list of policies.
                    required:
                      - policies
                  - $ref: '#/components/schemas/ListResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      x-audience: public
      summary: Create policy
      description: Create a policy that can be used to govern the behavior of accounts.
      operationId: createPolicy
      tags:
        - Policy Engine
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - policies#manage
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scope:
                  type: string
                  description: The scope of the policy.
                  enum:
                    - project
                    - account
                  example: project
                description:
                  type: string
                  description: |-
                    An optional human-readable description for the policy.
                    Policy descriptions can consist of alphanumeric characters, spaces, commas, and periods, and be 50 characters or less.
                  pattern: ^[A-Za-z0-9 ,.]{1,50}$
                  example: Default policy
                rules:
                  type: array
                  description: A list of rules that comprise the policy. There is a limit of 10 rules per policy.
                  items:
                    $ref: '#/components/schemas/Rule'
              required:
                - scope
                - rules
      responses:
        '201':
          description: Successfully created policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Policy name must be between 1 and 50 characters.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/policy-engine/policies/{policyId}:
    get:
      x-audience: public
      summary: Get policy by ID
      description: Get a policy by its ID.
      operationId: getPolicyById
      tags:
        - Policy Engine
      security:
        - apiKeyAuth: []
      parameters:
        - name: policyId
          description: The ID of the policy to get.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Successfully retrieved policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '404':
          description: Policy not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Policy not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    delete:
      x-audience: public
      summary: Delete policy
      description: Delete a policy by its ID. This will have the effect of removing the policy from all accounts that are currently using it.
      operationId: deletePolicy
      tags:
        - Policy Engine
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - policies#manage
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: policyId
          description: The ID of the policy to delete.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '204':
          description: Successfully deleted policy.
        '400':
          description: Unable to delete policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: policy_in_use
                    errorMessage: Policy in use.
        '404':
          description: Policy not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Policy not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      x-audience: public
      summary: Update policy
      description: Updates a policy by its ID. This will have the effect of applying the updated policy to all accounts that are currently using it.
      operationId: updatePolicy
      tags:
        - Policy Engine
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - policies#manage
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: policyId
          description: The ID of the policy to update.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 123e4567-e89b-12d3-a456-426614174000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: |-
                    An optional human-readable description for the policy.
                    Policy descriptions can consist of alphanumeric characters, spaces, commas, and periods, and be 50 characters or less.
                  pattern: ^[A-Za-z0-9 ,.]{1,50}$
                  example: Default policy
                rules:
                  type: array
                  description: A list of rules that comprise the policy. There is a limit of 10 rules per policy.
                  items:
                    $ref: '#/components/schemas/Rule'
              required:
                - rules
      responses:
        '200':
          description: Successfully updated policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Policy name must be between 1 and 50 characters.
        '404':
          description: Policy not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Policy not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts:
    get:
      x-audience: public
      summary: List Solana accounts
      description: |-
        Lists the Solana accounts belonging to the developer.
        The response is paginated, and by default, returns 20 accounts per page.

        If a name is provided, the response will contain only the account with that name.
      operationId: listSolanaAccounts
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully listed Solana accounts.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/SolanaAccount'
                        description: The list of Solana accounts.
                    required:
                      - accounts
                  - $ref: '#/components/schemas/ListResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      x-audience: public
      summary: Create Solana account
      description: Creates a new Solana account.
      operationId: createSolanaAccount
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: |-
                    An optional name for the account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all Solana accounts in the developer's CDP Project.
                  example: my-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
                accountPolicy:
                  type: string
                  x-audience: public
                  description: The ID of the account-level policy to apply to the account.
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '201':
          description: Successfully created Solana account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Project has no secret. Please register a secret with the project.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '409':
          description: Resource already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_exists:
                  value:
                    errorType: already_exists
                    errorMessage: Solana account with the given name already exists.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/{address}:
    get:
      x-audience: public
      summary: Get Solana account by address
      description: Gets a Solana account by its address.
      operationId: getSolanaAccount
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The base58 encoded address of the Solana account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
      responses:
        '200':
          description: Successfully got Solana account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "address": string doesn''t match the regular expression "^[1-9A-HJ-NP-Za-km-z]{32,44}$".'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      x-audience: public
      summary: Update Solana account
      description: Updates an existing Solana account. Use this to update the account's name or account-level policy.
      operationId: updateSolanaAccount
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The base58 encoded address of the Solana account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: |-
                    An optional name for the account. Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all Solana accounts in the developer's CDP Project.
                  example: my-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
                accountPolicy:
                  type: string
                  x-audience: public
                  description: The ID of the account-level policy to apply to the account, or an empty string to unset attached policy.
                  pattern: (^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^$)
                  example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Successfully updated Solana account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "name": string doesn''t match the regular expression  "^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$".'
        '404':
          description: Solana account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/by-name/{name}:
    get:
      x-audience: public
      summary: Get Solana account by name
      description: Gets a Solana account by its name.
      operationId: getSolanaAccountByName
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - name: name
          description: The name of the Solana account.
          in: path
          required: true
          schema:
            type: string
          example: my-account
      responses:
        '200':
          description: Successfully got Solana account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'error: parameter "name" must be a string.'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given name not found.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/import:
    post:
      x-audience: public
      summary: Import Solana account
      description: Import an existing Solana account into the developer's CDP Project. This API should be called from the [CDP SDK](https://github.com/coinbase/cdp-sdk) to ensure that the associated private key is properly encrypted.
      operationId: importSolanaAccount
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                encryptedPrivateKey:
                  type: string
                  description: The base64-encoded, encrypted 32-byte private key of the Solana account. The private key must be encrypted using the CDP SDK's encryption scheme.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                name:
                  type: string
                  description: |-
                    An optional name for the account.
                    Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
                    Account names must be unique across all EVM accounts in the developer's CDP Project.
                  example: my-solana-wallet
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
              required:
                - encryptedPrivateKey
      responses:
        '201':
          description: Successfully imported Solana account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolanaAccount'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: The encrypted private key is invalid.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '409':
          description: Resource already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                already_exists:
                  value:
                    errorType: already_exists
                    errorMessage: Solana account with the given address already exists.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/{address}/export:
    post:
      x-audience: public
      summary: Export Solana account
      description: Export an existing Solana account's private key. It is important to store the private key in a secure place after it's exported.
      operationId: exportSolanaAccount
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - accounts#export
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The base58 encoded address of the Solana account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                exportEncryptionKey:
                  type: string
                  description: The base64-encoded, public part of the RSA key in DER format used to encrypt the account private key.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
              required:
                - exportEncryptionKey
      responses:
        '200':
          description: Successfully exported Solana account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  encryptedPrivateKey:
                    type: string
                    description: The base64-encoded, encrypted private key of the Solana account which is a 32 byte raw private key. The private key is encrypted in transport using the exportEncryptionKey in the request.
                    example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                required:
                  - encryptedPrivateKey
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Solana account with the given address not found.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/export/by-name/{name}:
    post:
      x-audience: public
      summary: Export Solana account by name
      description: Export an existing Solana account's private key by its name. It is important to store the private key in a secure place after it's exported.
      operationId: exportSolanaAccountByName
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      x-required-api-auth-scopes:
        - accounts#export
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: name
          description: The name of the Solana account.
          in: path
          required: true
          schema:
            type: string
          example: my-account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                exportEncryptionKey:
                  type: string
                  description: The base64-encoded, public part of the RSA key in DER format used to encrypt the account private key.
                  example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
              required:
                - exportEncryptionKey
      responses:
        '200':
          description: Successfully exported Solana account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  encryptedPrivateKey:
                    type: string
                    description: The base64-encoded, encrypted private key of the Solana account which is a 32 byte raw private key. The private key is encrypted in transport using the exportEncryptionKey in the request.
                    example: U2FsdGVkX1+vupppZksvRf5X5YgHq4+da+Q4qf51+Q4=
                required:
                  - encryptedPrivateKey
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'error: parameter "name" must be a string.'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given name not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/{address}/sign/transaction:
    post:
      x-audience: public
      summary: Sign transaction
      description: |-
        Signs a transaction with the given Solana account.
        The unsigned transaction should be serialized into a byte array and then encoded as base64.

        **Transaction types**

        The following transaction types are supported:
        * [Legacy transactions](https://solana-labs.github.io/solana-web3.js/classes/Transaction.html)
        * [Versioned transactions](https://solana-labs.github.io/solana-web3.js/classes/VersionedTransaction.html)

        The developer is responsible for ensuring that the unsigned transaction is valid, as the API will not validate the transaction.
      operationId: signSolanaTransaction
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The base58 encoded address of the Solana account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction:
                  type: string
                  description: The base64 encoded transaction to sign.
                  example: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
              required:
                - transaction
      responses:
        '200':
          description: Successfully signed transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signedTransaction:
                    type: string
                    description: The base64 encoded signed transaction.
                    example: AQACAdSOvpk0UJXs/rQRXYKSI9hcR0bkGp24qGv6t0/M1XjcQpHf6AHwLcPjEtKQI7p/U0Zo98lnJ5/PZMfVq/0BAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                required:
                  - signedTransaction
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Solana account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/{address}/sign/message:
    post:
      x-audience: public
      summary: Sign message
      description: |-
        Signs an arbitrary message with the given Solana account.

        **WARNING:** Never sign a message that you didn't generate, as it can be an arbitrary transaction. For example, it might send all of your funds to an attacker.
      operationId: signSolanaMessage
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: address
          description: The base58 encoded address of the Solana account.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The arbitrary message to sign.
                  example: Hello, world!
              required:
                - message
      responses:
        '200':
          description: Successfully signed message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
                    description: The signature of the message, as a base58 encoded string.
                    example: 4YecmNqVT9QFqzuSvE9Zih3toZzNAijjXpj8xupgcC6E4VzwzFjuZBk5P99yz9JQaLRLm1K4L4FpMjxByFxQBe2h
                required:
                  - signature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "message": string doesn''t match the regular expression "^0x[0-9a-fA-F]{40}$".'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '404':
          description: Solana account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/accounts/send/transaction:
    post:
      x-audience: public
      summary: Send Solana transaction
      description: |-
        Signs and sends a single Solana transaction using multiple Solana accounts. The transaction may contain contain several instructions, each of which may require signatures from different account keys.

        The transaction should be serialized into a byte array and base64 encoded. The API handles recent blockhash management and fee estimation, leaving the developer to provide only the minimal set of fields necessary to send the transaction.

        **Transaction types**

        The following transaction types are supported:
        * [Legacy transactions](https://solana.com/developers/guides/advanced/versions#current-transaction-versions)
        * [Versioned transactions](https://solana.com/developers/guides/advanced/versions)

        **Instruction Batching**

        To batch multiple operations, include multiple instructions within a single transaction. All instructions within a transaction are executed atomically - if any instruction fails, the entire transaction fails and is rolled back.

        **Network Support**

        The following Solana networks are supported:
        * `solana` - Solana Mainnet
        * `solana-devnet` - Solana Devnet

        The developer is responsible for ensuring that the unsigned transaction is valid, as the API will not validate the transaction.
      operationId: sendSolanaTransaction
      tags:
        - Solana Accounts
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/XWalletAuth'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                network:
                  type: string
                  description: The Solana network to send the transaction to.
                  enum:
                    - solana
                    - solana-devnet
                  example: solana-devnet
                transaction:
                  type: string
                  description: The base64 encoded transaction to sign and send. This transaction can contain multiple instructions for native Solana batching.
                  example: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                useCdpSponsor:
                  type: boolean
                  description: Whether transaction fees should be sponsored by CDP. When true, CDP sponsors the transaction fees on behalf of the server wallet. When false, the server wallet is responsible for paying the transaction fees.
                  example: true
              required:
                - network
                - transaction
            examples:
              send_transaction:
                summary: Send a transaction
                value:
                  network: solana-devnet
                  transaction: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
              send_transaction_sponsored:
                summary: Send a transaction with CDP fee sponsorship
                value:
                  network: solana-devnet
                  transaction: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
                  useCdpSponsor: true
      responses:
        '200':
          description: Successfully signed and sent transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionSignature:
                    type: string
                    description: The base58 encoded transaction signature.
                    example: 5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW
                required:
                  - transactionSignature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformed_transaction:
                  value:
                    errorType: malformed_transaction
                    errorMessage: Malformed unsigned transaction.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    errorType: unauthorized
                    errorMessage: Wallet authentication error.
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to sign transaction for this address.
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Solana account with the given address not found.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/faucet:
    post:
      x-audience: public
      summary: Request funds on Solana devnet
      description: |
        Request funds from the CDP Faucet on Solana devnet.

        Faucets are available for SOL, USDC, and CBTUSD.

        To prevent abuse, we enforce rate limits within a rolling 24-hour window to control the amount of funds that can be requested.
        These limits are applied at both the CDP Project level and the blockchain address level.
        A single blockchain address cannot exceed the specified limits, even if multiple users submit requests to the same address.

        | Token  | Amount per Faucet Request |Rolling 24-hour window Rate Limits|
        |:-----: |:-------------------------:|:--------------------------------:|
        | SOL    | 0.00125 SOL               | 0.0125 SOL                       |
        | USDC   | 1 USDC                    | 10 USDC                          |
        | CBTUSD | 1 CBTUSD                  | 10 CBTUSD                        |
      operationId: requestSolanaFaucet
      tags:
        - Faucets
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The address to request funds to, which is a base58-encoded string.
                  pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
                  example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                token:
                  type: string
                  description: The token to request funds for.
                  enum:
                    - sol
                    - usdc
                    - cbtusd
                  example: sol
              required:
                - address
                - token
      responses:
        '200':
          description: Successfully requested funds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionSignature:
                    type: string
                    description: The signature identifying the transaction that requested the funds.
                    example: 4dje1d24iG2FfxwxTJJt8VSTtYXNc6AAuJwngtL97TJSqqPD3pgRZ7uh4szoU6WDrKyFTBgaswkDrCr7BqWjQqqK
                required:
                  - transactionSignature
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_address_format:
                  value:
                    errorType: invalid_request
                    errorMessage: 'request body has an error: doesn''t match schema: Error at "address": string doesn''t match the regular expression "^[1-9A-HJ-NP-Za-km-z]{32,44}$".'
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Unable to request faucet funds for this address.
        '403':
          description: Access to resource forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  value:
                    errorType: forbidden
                    errorMessage: Unable to request faucet funds for this address.
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                faucet_limit_exceeded:
                  value:
                    errorType: faucet_limit_exceeded
                    errorMessage: Faucet limit reached for this address. Please try again later.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/solana/token-balances/{network}/{address}:
    get:
      x-audience: public
      summary: List Solana token balances
      description: |-
        Lists the token balances of a Solana address on a given network. The balances include SPL tokens and the native SOL token. The response is paginated, and by default, returns 20 balances per page.

        **Note:** This endpoint is still under development and does not yet provide strong availability or freshness guarantees. Freshness and availability of new token balances will improve over the coming weeks.
      operationId: listSolanaTokenBalances
      tags:
        - Solana Token Balances
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The base58 encoded Solana address to get balances for.
          in: path
          required: true
          schema:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        - name: network
          description: The human-readable network name to get the balances for.
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ListSolanaTokenBalancesNetwork'
          example: solana
        - name: pageSize
          description: The number of balances to return per page.
          in: query
          required: false
          schema:
            type: integer
            default: 20
          example: 10
        - name: pageToken
          description: The token for the next page of balances. Will be empty if there are no more balances to fetch.
          in: query
          required: false
          schema:
            type: string
          example: eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ==
      responses:
        '200':
          description: Successfully listed token balances.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - balances
                    properties:
                      balances:
                        type: array
                        items:
                          $ref: '#/components/schemas/SolanaTokenBalance'
                        description: The list of Solana token balances.
                        example:
                          - amount:
                              amount: '1250000000'
                              decimals: 9
                            token:
                              symbol: SOL
                              name: Solana
                              mintAddress: So11111111111111111111111111111111111111111
                          - amount:
                              amount: '123456000'
                              decimals: 6
                            token:
                              symbol: USDC
                              name: USD Coin
                              mintAddress: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
                  - $ref: '#/components/schemas/ListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: string doesn't match the regular expression "^[1-9A-HJ-NP-Za-km-z]{32,44}$".
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Address not found, or no balances found for the given address on this chain.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/data/query/run:
    post:
      operationId: runSQLQuery
      summary: Run SQL Query
      x-audience: public
      description: |
        Run a read-only SQL query against indexed blockchain data including transactions, events, and decoded logs.

        This endpoint provides direct SQL access to comprehensive blockchain data across supported networks.

        Queries are executed against optimized data structures for high-performance analytics.

        ### Allowed Queries

          - Standard SQL syntax (CoinbaSeQL dialect, based on ClickHouse dialect)
          - Read-only queries (SELECT statements)
          - No DDL or DML operations
          - Query that follow limits (defined below)

        ### Supported Networks

          - Base Mainnet: `base`
          - Base Sepolia: `base_sepolia`
          - Solana Mainnet: `solana`
          - Hyperevm Mainnet: `hyperevm`

        ### Supported Tables

        The below tables are supported for `base` and `base_sepolia` networks.

          | Table | Description |
          | --- | --- |
          | `<network>.events` | Decoded event logs with parameters, event signature, topics, and more. |
          | `<network>.transactions` | Transaction data including hash, block number, and gas usage. |
          | `<network>.blocks` | Block information. |
          | `<network>.encoded_logs` | Encoded log data for event logs that cannot be decoded by our event decoder (ex: log0 opcode). |
          | `<network>.decoded_user_operations` | Decoded user operations data including hash, block number, gas usage, builder codes, entrypoint version, and more. |
          | `<network>.transaction_attributions` | Information about the attributions of a transaction to a builder and associated builder codes. |

          Following the above, the valid tables on Base Mainnet are `base.events`, `base.transactions`, `base.blocks`, `base.encoded_logs`, `base.decoded_user_operations`, and `base.transaction_attributions`.

        Separately, there is a limited set of tables supported for `solana` and `hyperevm` networks:

          | Table | Description |
          | --- | --- |
          | `solana.instructions` | Solana instruction call data including program ID, instruction data, and more. Currently supports just Token2022 and SPL Token programs. |
          | `hyperevm.events` | Hyperevm decoded event logs with parameters, event signature, topics, and more. Currently supports just B20 events. |

        ### Query Limits

          - Maximum result set: 50,000 rows
          - Maximum query length: 10,000 characters
          - Maximum on-disk data to read: 100GB
          - Maximum memory usage: 15GB
          - Query timeout: 30 seconds
          - Maximum JOINs: 12

        ### Query Caching

        By default, each query result is returned from cache so long as the result is from an identical query and less than 750ms old. This freshness tolerance can be modified upwards, to a maximum of 900000ms (i.e. 900s, 15m).
        This can be helpful for users who wish to reduce expensive calls to the SQL API by reusing cached results.
      tags:
        - SQL API
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnchainDataQuery'
      responses:
        '200':
          description: Query run successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnchainDataResult'
        '400':
          $ref: '#/components/responses/InvalidSQLQueryError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '408':
          description: Query timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                query_timeout:
                  value:
                    errorType: timed_out
                    errorMessage: Query execution was cut off by the server. Please try again with a more efficient query.
        '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.
        '499':
          $ref: '#/components/responses/ClientClosedRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/TimedOutError'
  /v2/data/query/grammar:
    get:
      operationId: getSQLGrammar
      summary: Get SQL grammar
      x-audience: public
      description: |
        Retrieve the SQL grammar for the SQL API.

        The SQL queries that are supported by the SQL API are defined in ANTLR4 grammar which is evaluated by server before executing the query. This ensures the safety and soundness of the SQL query before execution.

        This endpoint returns the ANTLR4 grammar that is used to evaluate the SQL queries so that developers can understand the SQL API and build SQL queries with high confidence and correctness.

        LLMs interact well with ANTLR4 grammar. You can feed the grammar directly into the LLMs to help generate SQL queries.
      tags:
        - SQL API
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: SQL grammar retrieved successfully.
          content:
            application/json:
              schema:
                type: string
                description: The ANTLR4 grammar for the SQL API.
                example: 'grammar SqlQuery; query: cteClause? unionStatement SEMICOLON? EOF;'
        '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'
        '504':
          $ref: '#/components/responses/TimedOutError'
  /v2/data/query/schema:
    get:
      operationId: getSQLSchema
      summary: Get schema details
      x-audience: public
      description: |
        Retrieve the schema information for the available tables in the SQL API's indexed data.

        This includes table names, column definitions, data types, and indexed fields.
      tags:
        - SQL API
      security:
        - apiKeyAuth: []
      parameters:
        - name: database
          in: query
          required: false
          description: The name of the database to query. Defaults to "base" when not specified.
          schema:
            type: string
            enum:
              - base
              - base_sepolia
              - solana
              - hyperevm
            default: base
          example: base
        - name: table
          in: query
          required: false
          description: Get the schema for a specific table.
          schema:
            type: string
          example: events
      responses:
        '200':
          description: Schema information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnchainDataSchemaResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/data/evm/token-ownership/{network}/{address}:
    get:
      operationId: listTokensForAccount
      summary: List token addresses for account
      x-audience: public
      description: |
        Retrieve all ERC-20 token contract addresses that an account has ever received tokens from.
        Analyzes transaction history to discover token interactions.
      tags:
        - Onchain Data
      security:
        - apiKeyAuth: []
      parameters:
        - name: network
          in: path
          required: true
          description: The blockchain network to query.
          schema:
            type: string
            enum:
              - base
              - base-sepolia
          example: base
        - name: address
          in: path
          required: true
          description: The account address to analyze for token interactions.
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      responses:
        '200':
          description: Token addresses retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTokenAddressesResponse'
        '400':
          description: Invalid account address format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_address:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid account address format. Address must be 40 hex characters prefixed with '0x'.
        '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/evm/token-balances/{network}/{address}:
    get:
      summary: List EVM token balances
      x-audience: public
      description: |-
        Lists the token balances of an EVM address on a given network. The balances include ERC-20 tokens and the native gas token (usually ETH). The response is paginated, and by default, returns 20 balances per page.

        Calls to the `base` and `base-sepolia` networks offer:
          * 99.5% < 2 second freshness from chain tip for new tokens on an address.
          * 99.5% < 2 second freshness from chain tip for balance data.

        Calls to the `ethereum` network offer:
          * 99% < 30 second freshness from chain tip for new tokens on an address.
          * 99% < 2 second freshness from chain tip for balance data.
      operationId: listDataTokenBalances
      tags:
        - Onchain Data
      security:
        - apiKeyAuth: []
      parameters:
        - name: address
          description: The 0x-prefixed EVM address to get balances for. The address does not need to be checksummed.
          in: path
          required: true
          schema:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: network
          description: The human-readable network name to get the balances for.
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ListEvmTokenBalancesNetwork'
          example: base
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successfully listed token balances.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - balances
                    properties:
                      balances:
                        type: array
                        items:
                          $ref: '#/components/schemas/TokenBalance'
                        description: The list of EVM token balances.
                        example:
                          - amount:
                              amount: '1250000000000000000'
                              decimals: 18
                            token:
                              network: base
                              symbol: ETH
                              name: ether
                              contractAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
                          - amount:
                              amount: '123456'
                              decimals: 6
                            token:
                              network: base
                              symbol: USDC
                              name: USD Coin
                              contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                  - $ref: '#/components/schemas/ListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: string doesn't match the regular expression "^0x[0-9a-fA-F]{40}$".
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Address not found, or no balances found for the given address on this chain.
        '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: []
      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: []
      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: []
      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: []
      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: []
      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: []
      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/x402/verify:
    post:
      x-audience: public
      summary: Verify payment
      description: Verify an x402 protocol payment with a specific scheme and network.
      operationId: verifyX402Payment
      tags:
        - x402 Facilitator
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                x402Version:
                  $ref: '#/components/schemas/X402Version'
                paymentPayload:
                  $ref: '#/components/schemas/x402PaymentPayload'
                paymentRequirements:
                  $ref: '#/components/schemas/x402PaymentRequirements'
              required:
                - x402Version
                - paymentPayload
                - paymentRequirements
      responses:
        '200':
          $ref: '#/components/responses/x402VerifyResponse'
        '400':
          $ref: '#/components/responses/x402VerifyInvalidError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/settle:
    post:
      x-audience: public
      summary: Settle payment
      description: Settle an x402 protocol payment with a specific scheme and network.
      operationId: settleX402Payment
      tags:
        - x402 Facilitator
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                x402Version:
                  $ref: '#/components/schemas/X402Version'
                paymentPayload:
                  $ref: '#/components/schemas/x402PaymentPayload'
                paymentRequirements:
                  $ref: '#/components/schemas/x402PaymentRequirements'
              required:
                - x402Version
                - paymentPayload
                - paymentRequirements
      responses:
        '200':
          $ref: '#/components/responses/x402SettleResponse'
        '400':
          $ref: '#/components/responses/x402SettleError'
        '402':
          $ref: '#/components/responses/PaymentMethodRequiredError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/supported:
    get:
      x-audience: public
      summary: Get supported payment schemes and networks
      description: Get the supported x402 protocol payment schemes and networks that the facilitator is able to verify and settle payments for.
      operationId: supportedX402PaymentKinds
      tags:
        - x402 Facilitator
      security:
        - apiKeyAuth: []
      responses:
        '200':
          $ref: '#/components/responses/x402SupportedPaymentKindsResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/discovery/resources:
    get:
      x-audience: public
      summary: List x402 resources
      description: |-
        Lists all active discovered x402 resources.
        This endpoint returns resources that have been discovered and cached by the x402 facilitator, including their payment requirements and metadata.
        The response is paginated, and by default, returns 100 items per page.
      operationId: listX402DiscoveryResources
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      parameters:
        - name: type
          in: query
          description: |-
            Filter by protocol type (e.g., "http", "mcp").
            Currently, the only supported protocol type is "http".
          required: false
          schema:
            type: string
            example: http
        - name: limit
          in: query
          description: The number of discovered x402 resources to return per page.
          required: false
          schema:
            type: integer
            default: 100
          example: 50
        - name: offset
          in: query
          description: The offset of the first discovered x402 resource to return.
          required: false
          schema:
            type: integer
            default: 0
          example: 0
      responses:
        '200':
          description: Successfully retrieved discovery list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402DiscoveryResourcesResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request parameters.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/discovery/merchant:
    get:
      x-audience: public
      summary: List merchant discovery info
      description: |-
        Gets x402 merchant discovery information for a given merchant payment address.
        This endpoint returns all active x402 resources associated with the specified `payTo` address, allowing clients to discover what payment-gated resources a merchant exposes and their corresponding payment requirements.
        If no active resources are found for the `payTo` address, the endpoint returns an empty `resources` list.
        The response is paginated, and by default, returns 20 items per page.
      operationId: listX402DiscoveryMerchant
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      parameters:
        - name: payTo
          in: query
          description: |-
            The merchant's payment address to look up.
            This is the onchain address that payment requirements route funds to.
          required: true
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: limit
          in: query
          description: The number of resources to return per page.
          required: false
          schema:
            type: integer
            default: 20
          example: 20
        - name: offset
          in: query
          description: The offset of the first resource to return.
          required: false
          schema:
            type: integer
            default: 0
          example: 0
      responses:
        '200':
          description: Successfully retrieved merchant discovery info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402DiscoveryMerchantResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. Please check the request parameters.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/discovery/search:
    get:
      x-audience: public
      summary: Search x402 resources
      description: |-
        Searches for active x402 resources using a text query and optional filters.
        Supports both text-based and vector-based search depending on availability. Results are sorted by relevance and quality score.
        Legacy network names (e.g., `base`, `base-sepolia`, `solana`) are automatically normalized to their CAIP-2 equivalents.
        The response is limited to 20 items per request. If more results exist, `partialResults` will be `true`.
      operationId: searchX402Resources
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      parameters:
        - name: query
          in: query
          description: Full-text or semantic search query to find matching resources.
          required: false
          schema:
            type: string
            maxLength: 400
            example: weather forecast
        - name: network
          in: query
          description: |-
            Filter results by network in CAIP-2 format (e.g., `eip155:8453`) or legacy name (e.g., `base`, `base-sepolia`, `solana`).
            Legacy names are normalized to their CAIP-2 equivalents before filtering.
          required: false
          schema:
            type: string
            example: eip155:8453
        - name: asset
          in: query
          description: |-
            Filter results by asset address.
            For EVM networks, provide a 0x-prefixed EVM address. For Solana networks, provide a base58-encoded address.
            Matching is case-insensitive.
          required: false
          schema:
            type: string
            example: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
        - name: scheme
          in: query
          description: Filter results by payment scheme (e.g., `exact`).
          required: false
          schema:
            type: string
            example: exact
        - name: payTo
          in: query
          description: |-
            Filter results by the merchant's payment address.
            For EVM networks, provide a 0x-prefixed EVM address. For Solana networks, provide a base58-encoded address.
          required: false
          schema:
            $ref: '#/components/schemas/BlockchainAddress'
            example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        - name: urlSubstring
          in: query
          description: |-
            Filter results to resources whose URL contains this value (case-insensitive substring match against the resource URL).
            Useful for narrowing results to a specific domain, subdomain, or path segment. Combine with `query` to perform semantic search restricted to a URL subset.
            Tip: include enough of the URL to disambiguate (e.g. `api.example.com` rather than `example`) — a short substring may also match resources whose path contains the same string.
          required: false
          schema:
            type: string
            minLength: 3
            maxLength: 2048
            example: api.example.com
        - name: maxUsdPrice
          in: query
          description: Filter results to resources with a USD price at or below this value.
          required: false
          schema:
            type: string
            example: '1.00'
        - name: extensions
          in: query
          description: Filter results to resources that support the specified protocol extensions. Can be specified multiple times to filter by multiple extensions.
          required: false
          schema:
            type: array
            items:
              type: string
            example:
              - bazaar
          style: form
          explode: true
        - name: tags
          in: query
          description: Filter results to resources published with any of the specified provider tags (case-sensitive exact match). Can be specified multiple times to filter by multiple tags; a resource matches if it carries at least one of the supplied tags (OR).
          required: false
          schema:
            type: array
            maxItems: 5
            items:
              type: string
            example:
              - weather
              - data
          style: form
          explode: true
        - name: bundleSlugs
          in: query
          description: Filter results to resources that belong to any of the specified curated bundles (by bundle slug). Can be specified multiple times to filter by multiple bundles; a resource matches if it belongs to at least one of the supplied bundles (OR).
          required: false
          schema:
            type: array
            maxItems: 5
            items:
              type: string
              maxLength: 64
              pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
            example:
              - defi-trading
              - onchain-data
          style: form
          explode: true
        - name: curatedOnly
          in: query
          description: 'When `true`, restrict results to Coinbase-curated resources (those with `curated: true`). When `false` or omitted, both curated and non-curated resources are returned.'
          required: false
          schema:
            type: boolean
            default: false
            example: true
        - name: limit
          in: query
          description: |-
            Maximum number of resources to return. Must be a positive integer no greater than 20.
            Defaults to 20.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 20
            minimum: 1
          example: 20
      responses:
        '200':
          description: Successfully retrieved matching x402 resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402SearchResourcesResponse'
              examples:
                search_results:
                  value:
                    x402Version: 2
                    resources:
                      - resource: https://api.example.com/weather/forecast
                        description: Real-time weather forecast data.
                        type: http
                        x402Version: 2
                        lastUpdated: '2024-01-15T10:30:00Z'
                        extensions:
                          bazaar:
                            info:
                              input:
                                type: http
                                method: GET
                            schema: {}
                        accepts:
                          - scheme: exact
                            network: eip155:8453
                            amount: '1000000'
                            payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                            asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                            maxTimeoutSeconds: 60
                        quality:
                          l30DaysTotalCalls: 42
                          l30DaysUniquePayers: 15
                          lastCalledAt: '2024-01-15T10:30:00Z'
                        curated: true
                        skillUrl: https://skills.cdp.coinbase.com/weather-api/SKILL.md
                    partialResults: false
                    searchMethod: text
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: limit must be a positive integer.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/discovery/mcp:
    post:
      x-audience: public
      summary: Handle MCP JSON-RPC request
      description: Handles JSON-RPC requests for the Model Context Protocol (MCP). Supports MCP methods for discovering x402 payment resources and tools.
      operationId: postX402DiscoveryMcp
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/x402McpRequest'
      responses:
        '200':
          description: MCP response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402McpResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid JSON-RPC request. Please check the request format.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/x402/discovery/bundles:
    get:
      x-audience: public
      summary: List x402 bundles
      description: |-
        Lists the available curated x402 workflow bundles. A bundle is an ordered, named grouping of curated x402 resources that together cover a common agent workflow.
        The result set is small and server-controlled, so this endpoint is not paginated.
      operationId: listX402Bundles
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      responses:
        '200':
          description: Successfully retrieved the available curated bundles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402BundlesResponse'
              examples:
                bundles:
                  value:
                    bundles:
                      - slug: defi-trading
                        name: DeFi Trading
                        description: Endpoints for discovering prices, routing swaps, and settling trades onchain.
                      - slug: market-data
                        name: Market Data
                        description: Endpoints for real-time and historical market data.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/discovery/bundles/{bundleSlug}:
    get:
      x-audience: public
      summary: Get an x402 bundle
      description: Gets a single curated x402 workflow bundle by its bundle slug, including the bundle metadata and its ordered member resources joined to their full discovery metadata.
      operationId: getX402Bundle
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      parameters:
        - name: bundleSlug
          in: path
          description: The unique, URL-safe slug identifying the bundle (as returned by `GET /v2/x402/discovery/bundles`).
          required: true
          schema:
            type: string
            maxLength: 64
            pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
            example: defi-trading
      responses:
        '200':
          description: Successfully retrieved the bundle and its member resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402BundleResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Bundle slug must match the required format.
        '404':
          description: No bundle found with the given slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: No bundle found with the given slug.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/x402/validate:
    post:
      x-audience: public
      summary: Validate x402 endpoint
      description: |-
        Validates an x402 endpoint's bazaar-discovery configuration by probing the seller's URL live.
        Returns a uniform array of preflight check results (reachable, returns402, hasBazaarExtension, parse) and a simulated facilitator accept/reject decision so sellers and agents can confirm their endpoint is ready to be discovered before going live.
        This operation is read-only: it performs no payment and does not index the resource.
      operationId: validateX402Resource
      tags:
        - x402 Facilitator
      security:
        - unauthenticated: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/x402ValidateRequest'
      responses:
        '200':
          description: Successfully validated the x402 endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/x402ValidateResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid request. resource is required and must be a valid HTTPS URL.
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailableError'
  /v2/onramp/verifications:
    post:
      x-audience: public
      summary: Initiate onramp verification
      description: |-
        Initiates OTP verification by sending a 6-digit code to the user via the specified channel (SMS or email). Returns a `verificationId` that must be passed to the Submit Onramp Verification endpoint along with the OTP code within 10 minutes.

        **Access to this API requires allowlisting.** During Onramp Headless API onboarding, contact the Onramp team to enable Onramp-managed verification for your application.
      operationId: initiateOnrampVerification
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateOnrampVerificationRequest'
      responses:
        '201':
          description: Successfully initiated onramp verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnrampVerificationInitiation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid channel or destination.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/onramp/verifications/{verificationId}/submit:
    post:
      x-audience: public
      summary: Submit onramp verification
      description: |-
        Submits the OTP code to complete verification. On success, marks the verification as verified and returns the same `verificationId`. The destination does not need to be re-sent. Onramp uses the value captured at initiation time.

        The returned `verificationId` should be stored on the user's device and passed to the Create Onramp Order endpoint. It is valid for 60 days.

        **Access to this API requires allowlisting.** During Onramp Headless API onboarding, contact the Onramp team to enable Onramp-managed verification for your application.
      operationId: submitOnrampVerification
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      parameters:
        - name: verificationId
          in: path
          required: true
          description: The verification ID returned by the Initiate Onramp Verification endpoint.
          schema:
            $ref: '#/components/schemas/OnrampVerificationId'
          example: onramp_verification_a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitOnrampVerificationRequest'
      responses:
        '200':
          description: Successfully completed onramp verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnrampVerificationConfirmation'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: OTP code is required.
                verification_code_invalid:
                  value:
                    errorType: otp_verification_code_invalid
                    errorMessage: The OTP code is incorrect or has expired.
                verification_invalid:
                  value:
                    errorType: otp_verification_invalid
                    errorMessage: The verification record is not in a usable state for this operation.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Verification not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                verification_not_found:
                  value:
                    errorType: otp_verification_not_found
                    errorMessage: The provided verification ID does not correspond to any verification record.
        '422':
          $ref: '#/components/responses/IdempotencyError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/onramp/orders:
    post:
      x-audience: public
      summary: Create an onramp order
      description: |-
        Create a new Onramp order or get a quote for an Onramp order. Either `paymentAmount` or `purchaseAmount` must be provided.

        This API supports two modes:

        **Headless mode (standard)**: returns a seamless Apple Pay or Google Pay button that you integrate directly into your app. Your app collects and verifies the user's contact details before calling this endpoint — `phoneNumber`, `email`, `phoneNumberVerifiedAt`, and `agreementAcceptedAt` are required and enforced server-side.

        **Embedded mode**: returns a webview that collects and verifies the user's contact and identity information, then shows the payment screen. Omit both `phoneNumber` and `email` from the request to select this mode. Embedded mode requires account enablement; contact the Onramp team for access.

        Read more about the difference between the two modes in the [Headless Onramp overview](https://docs.cdp.coinbase.com/onramp/headless-onramp/overview).

        This API supports the `GUEST_CHECKOUT_APPLE_PAY` and `GUEST_CHECKOUT_GOOGLE_PAY` payment methods.

        For detailed integration instructions and to get access to this API, refer to the  [Guest Checkout Onramp API docs](https://docs.cdp.coinbase.com/onramp/headless-onramp/overview).
      operationId: createOnrampOrder
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agreementAcceptedAt:
                  description: The timestamp of when the user acknowledged that by using Coinbase Onramp they are accepting the Coinbase Terms (https://www.coinbase.com/legal/guest-checkout/us), User Agreement (https://www.coinbase.com/legal/user_agreement),  and Privacy Policy (https://www.coinbase.com/legal/privacy).
                  format: date-time
                  type: string
                  example: '2025-04-24T00:00:00Z'
                destinationAddress:
                  allOf:
                    - $ref: '#/components/schemas/BlockchainAddress'
                  description: The address the purchased crypto will be sent to.
                destinationNetwork:
                  description: |-
                    The name of the crypto network the purchased currency will be sent on.

                    Use the [Onramp Buy Options API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-buy-options) to discover the supported networks for your user's location.
                  type: string
                  example: base
                email:
                  description: The verified email address of the user requesting the onramp transaction. This email must be verified by your app (via OTP) before being used with the Onramp API.
                  type: string
                  example: test@example.com
                isQuote:
                  description: If true, this API will return a quote without creating any transaction.
                  type: boolean
                  default: false
                partnerOrderRef:
                  description: Optional partner order reference ID.
                  type: string
                  example: order-1234
                partnerUserRef:
                  description: |-
                    A unique string that represents the user in your app. This can be used to link individual transactions  together so you can retrieve the transaction history for your users. Prefix this string with “sandbox-”  (e.g. "sandbox-user-1234") to perform a sandbox transaction which will allow you to test your integration  without any real transfer of funds.

                    This value can be used with with [Onramp User Transactions API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-onramp-transactions-by-id) to retrieve all transactions created by the user.
                  type: string
                  example: user-1234
                paymentAmount:
                  description: A string representing the amount of fiat the user wishes to pay in exchange for crypto. When using  this parameter, the returned quote will be inclusive of fees i.e. the user will pay this exact amount  of the payment currency.
                  type: string
                  example: '100.00'
                paymentCurrency:
                  description: The fiat currency to be converted to crypto.
                  type: string
                  example: USD
                paymentMethod:
                  $ref: '#/components/schemas/OnrampOrderPaymentMethodTypeId'
                phoneNumber:
                  description: |-
                    The phone number of the user requesting the onramp transaction in E.164 format. This phone number must  be verified by your app (via OTP) before being used with the Onramp API.
                    Please refer to the [Onramp docs](https://docs.cdp.coinbase.com/onramp/headless-onramp/overview) for more details on phone number verification requirements and best practices.
                  type: string
                  example: '+12055555555'
                phoneNumberVerifiedAt:
                  description: Timestamp of when the user's phone number was verified via OTP. User phone number must be verified every 60 days. If this timestamp is older than 60 days, an error will be returned.
                  format: date-time
                  type: string
                  example: '2025-04-24T00:00:00Z'
                smsVerificationId:
                  allOf:
                    - $ref: '#/components/schemas/OnrampVerificationId'
                  description: The SMS verification ID returned by the Submit Onramp Verification endpoint after verifying the user's phone number. When provided, Onramp validates the server-side verification record instead of trusting `phoneNumberVerifiedAt`.
                emailVerificationId:
                  allOf:
                    - $ref: '#/components/schemas/OnrampVerificationId'
                  description: The email verification ID returned by the Submit Onramp Verification endpoint after verifying the user's email address.
                purchaseAmount:
                  description: A string representing the amount of crypto the user wishes to purchase. When using this parameter the  returned quote will be exclusive of fees i.e. the user will receive this exact amount of the purchase  currency.
                  type: string
                  example: '10.000000'
                purchaseCurrency:
                  description: |-
                    The ticker (e.g. `BTC`, `USDC`, `SOL`) or the Coinbase UUID (e.g. `d85dce9b-5b73-5c3c-8978-522ce1d1c1b4`)  of the crypto asset to be purchased.

                    Use the [Onramp Buy Options API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-buy-options) to discover the supported purchase currencies for your user's location.
                  type: string
                  example: USDC
                clientIp:
                  description: The IP address of the end user requesting the onramp transaction.
                  type: string
                  example: 127.0.0.1
                domain:
                  description: The domain that the Apple Pay or Google Pay button will be rendered on. Required when using the `GUEST_CHECKOUT_APPLE_PAY` or `GUEST_CHECKOUT_GOOGLE_PAY` payment method and embedding the payment link in an iframe. Omit this field entirely for mobile iOS Apple Pay via WebView integration.
                  type: string
                  example: pay.coinbase.com
                locale:
                  type: string
                  pattern: ^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$
                  description: Optional [BCP-47](https://www.rfc-editor.org/info/bcp47) locale tag (e.g. `es-ES`, `pt-BR`, `en`) used to localize the hosted payment page. When provided, it is appended to the returned `paymentLink` URL and mapped to the closest locale supported by the Apple Pay and Google Pay buttons; unsupported locales fall back to the user's browser language. Any well-formed BCP-47 tag is accepted.
                  example: es-ES
                userAuthToken:
                  allOf:
                    - $ref: '#/components/schemas/OnrampUserAuthToken'
                  description: Optional. A reusable token returned by a previous verified order. When provided, a returning user checking out to the same wallet is taken straight to the pay button, skipping OTP (best-effort — an invalid, expired, or different-wallet token still requires verification).
              required:
                - paymentCurrency
                - purchaseCurrency
                - paymentMethod
                - destinationAddress
                - destinationNetwork
                - partnerUserRef
      responses:
        '201':
          description: Successfully created an onramp order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/OnrampOrder'
                  paymentLink:
                    $ref: '#/components/schemas/OnrampPaymentLink'
                  userAuthToken:
                    allOf:
                      - $ref: '#/components/schemas/OnrampUserAuthToken'
                    description: Present for embedded orders once the user has verified. Store this and pass it on future orders for the same user to skip OTP verification. Valid for 60 days.
                required:
                  - order
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Missing required params.
                network_not_tradable:
                  value:
                    errorType: network_not_tradable
                    errorMessage: The selected asset cannot be purchased on the selected network in the user's location.
                guest_permission_denied:
                  value:
                    errorType: guest_permission_denied
                    errorMessage: The user is not allowed to complete onramp transactions as a guest.
                guest_region_forbidden:
                  value:
                    errorType: guest_region_forbidden
                    errorMessage: Guest onramp transactions are not allowed in the user's region.
                phone_number_verification_expired:
                  value:
                    errorType: phone_number_verification_expired
                    errorMessage: The user's phone number verification has expired. Please re-verify the user's phone number.
                verification_expired:
                  value:
                    errorType: otp_verification_expired
                    errorMessage: The verification record has expired. Initiate a new verification flow.
                verification_invalid:
                  value:
                    errorType: otp_verification_invalid
                    errorMessage: The verification record is not in a valid state for order placement.
                verification_required:
                  value:
                    errorType: otp_verification_required
                    errorMessage: Verification is required for this application. Use the Onramp Verification API to verify the user's phone number and email.
                verification_destination_mismatch:
                  value:
                    errorType: otp_verification_destination_mismatch
                    errorMessage: The destination on the order does not match the destination that was verified.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Verification not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                verification_not_found:
                  value:
                    errorType: otp_verification_not_found
                    errorMessage: The provided verification ID does not correspond to any verification record.
        '429':
          description: Rate limit or guest transaction quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limit_exceeded:
                  value:
                    errorType: rate_limit_exceeded
                    errorMessage: Rate limit exceeded.
                guest_transaction_limit:
                  value:
                    errorType: guest_transaction_limit
                    errorMessage: This transaction would exceed the user's weekly guest onramp transaction limit.
                guest_transaction_count:
                  value:
                    errorType: guest_transaction_count
                    errorMessage: The user has reached the lifetime guest onramp transaction count limit (15).
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/onramp/orders/{orderId}:
    get:
      x-audience: public
      summary: Get an onramp order by ID
      description: Get an onramp order by ID.
      operationId: getOnrampOrderById
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          description: The ID of the onramp order to retrieve.
          schema:
            type: string
            pattern: ^[a-f0-9\-]{36}$
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Successfully retrieved an onramp order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/OnrampOrder'
                required:
                  - order
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    errorType: not_found
                    errorMessage: Order with the given ID does not exist.
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /v2/onramp/sessions:
    post:
      x-audience: public
      summary: Create an onramp session
      description: |-
        Returns a single-use URL for an Onramp session. This API provides flexible  functionality based on the parameters provided, supporting three cases:

        **Important**: The returned URL is single-use only. Once a user visits the URL,  no one else can access it.
        ## Use Cases
        ### 1. Basic Session (Minimum Parameters)
        **Required**: `destinationAddress`, `purchaseCurrency`, `destinationNetwork`

        **Returns**: Basic single-use onramp URL. The `quote` object will not be included in the response.
        ### 2. One-Click Onramp URL
        **Required**: Basic parameters + (`paymentAmount` OR `purchaseAmount`), `paymentCurrency`

        **Returns**: One-click onramp URL for streamlined checkout. The `quote` object will not be included in the response.
        ### 3. One-Click Onramp URL with Quote
        **Required**: One-Click Onramp parameters + `paymentMethod`, `country`, `subdivision`

        **Returns**: Complete pricing quote and one-click onramp URL. Both `session` and `quote` objects will be included in the response.

        **Note**: Only one of `paymentAmount` or `purchaseAmount` should be provided, not both. Providing both will result in an error. When `paymentAmount` is provided, the quote shows how much crypto the user will receive for the specified fiat amount (fee-inclusive). When `purchaseAmount` is provided, the quote shows how much fiat the user needs to pay for the specified crypto amount (fee-exclusive).
      operationId: createOnrampSession
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampSessionRequest'
      responses:
        '201':
          description: Onramp session created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session:
                    $ref: '#/components/schemas/OnrampSession'
                  quote:
                    $ref: '#/components/schemas/OnrampQuote'
                required:
                  - session
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Missing required parameters.
                invalid_destination_address:
                  value:
                    errorType: invalid_request
                    errorMessage: The destination address is not valid for the specified network.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/onramp/limits:
    post:
      summary: Get onramp user limits
      x-audience: public
      description: |-
        Returns the transaction limits for an onramp user based on their payment method and user identifier. Use this API to show users their remaining purchase capacity before initiating an onramp transaction.
        Currently supports `GUEST_CHECKOUT_APPLE_PAY` payment method with phone number identification. The phone number must have been previously verified via OTP.
      operationId: getOnrampUserLimits
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentMethodType:
                  $ref: '#/components/schemas/OnrampOrderPaymentMethodTypeId'
                userId:
                  type: string
                  description: The user identifier value. For `phone_number` type, this must be in E.164 format.
                  example: '+12055555555'
                userIdType:
                  $ref: '#/components/schemas/OnrampUserIdType'
              required:
                - paymentMethodType
                - userId
                - userIdType
      responses:
        '200':
          description: Successfully retrieved user limits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  limits:
                    type: array
                    description: The list of limits applicable to the user.
                    items:
                      $ref: '#/components/schemas/OnrampUserLimit'
                  limitUpgradeOptions:
                    type: array
                    description: The user's limit upgrade status and associated upgrade details. Omitted when limit upgrades are not available for the calling app or user. Use the [Request Limit Upgrade](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/onramp/request-limits-upgrade) endpoint to request a limit upgrade.
                    items:
                      $ref: '#/components/schemas/OnrampLimitUpgradeOption'
                required:
                  - limits
              examples:
                default:
                  value:
                    limits:
                      - limitType: weekly_spending
                        currency: USD
                        limit: '500'
                        remaining: '400'
                      - limitType: lifetime_transactions
                        limit: '15'
                        remaining: '12'
                    limitUpgradeOptions:
                      - status: unrequested
                        fields:
                          - ssnLast4
                          - dateOfBirth
                        limitUpgrades:
                          - limitType: weekly_spending
                            maxUpgrade: '2500'
                          - limitType: lifetime_transactions
                            maxUpgrade: '2147483647'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Must provide a valid payment method type and user identifier.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/onramp/limits/upgrade:
    post:
      summary: Request limit upgrade
      x-audience: public
      description: |-
        Requests a limit upgrade for an onramp user. Only phone number is currently supported as a userId.

        The default API mode submits identity information directly and returns HTTP 202 when the request is accepted. Embedded mode (`interactionMode: embedded`) returns a Coinbase-hosted `upgradeUrl` where the user enters identity information.

        The verification process is asynchronous. After calling this endpoint, use the [Get Onramp User Limits](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/onramp/get-onramp-user-limits) endpoint to check the status in the `limitUpgradeOptions` array.

        **Prerequisites:**
        - The phone number must have been previously verified by your app via OTP. - Upgrades may not be available until a certain number of successful transactions by the user.

        **Supported fields:**
        - `ssnLast4`: Last 4 digits of the Social Security Number (no dashes or spaces).
        - `dateOfBirth`: Date of birth (day, month, year as zero-padded strings).
      operationId: requestLimitsUpgrade
      tags:
        - Onramp
      security:
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampLimitUpgradeRequest'
            example:
              userId: '+12055555555'
              userIdType: phone_number
              fields:
                ssnLast4: '5678'
                dateOfBirth:
                  day: '15'
                  month: '08'
                  year: '1990'
      responses:
        '200':
          description: Embedded limit upgrade URL created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnrampLimitUpgradeEmbeddedResponse'
        '202':
          description: Limit upgrade request accepted.
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    errorType: invalid_request
                    errorMessage: Invalid user identifier or fields.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '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: []
      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: []
      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:
  onchainActivityDetected:
    post:
      summary: Onchain activity detected
      description: Triggered when onchain activity matching your subscription filters is detected. Your API will receive a POST request at the webhook URL you configured. Use `labels` on your webhook subscription to filter which onchain events are delivered (see the Create Webhook Subscription endpoint for allowed labels).
      operationId: onchainActivityDetectedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onchain Data
      requestBody:
        description: The decoded blockchain event data. Payload shape varies by the type of onchain activity detected (token transfer, contract interaction, etc.).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnchainActivityDetectedEvent'
            examples:
              erc20_transfer:
                summary: ERC-20 token transfer detected
                value:
                  block_number: 46218191
                  contract_address: '0x940181a94A35A4569E4529A3CDfB74e38FD98631'
                  event_name: Transfer
                  event_signature: Transfer(address,address,uint256)
                  log_index: 29
                  network: base-mainnet
                  parameters:
                    from: '0xF33a96b5932D9E9B9A0eDA447AbD8C9d48d2e0c8'
                    to: '0x61040E143A77F165Ba44543AF4A079F2C809D14b'
                    value: '474891138228179365'
                  timestamp: '2026-05-19T21:22:10Z'
                  transaction_from: '0x3E16D476D8Df15e3E776EAa5A46f37EC44C830cD'
                  transaction_hash: '0xa58e4471bcce875b1ea49cc0864a620d3a484b9b7c1b0b4fd18ce83f5b30e5e0'
                  transaction_to: '0x61040E143A77F165Ba44543AF4A079F2C809D14b'
      responses:
        '200':
          description: Webhook received and processed successfully. Return a 200 status code to acknowledge receipt. If your endpoint does not return a 2xx status code, the webhook will be retried with exponential backoff.
        '401':
          description: Invalid signature. The webhook signature verification failed.
  walletActivityDetected:
    post:
      summary: Wallet activity detected
      description: Triggered when the `wallet.activity.detected` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletActivityDetectedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onchain Data
      requestBody:
        description: The `wallet.activity.detected` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletActivityDetectedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletActivityMulti:
    post:
      summary: Wallet activity multi
      description: Triggered when the `wallet.activity.multi` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletActivityMultiWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onchain Data
      requestBody:
        description: The `wallet.activity.multi` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletActivityMultiEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionCreated:
    post:
      summary: Wallet transaction created
      description: Triggered when the `wallet.transaction.created` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionCreatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.created` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionCreatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionSigned:
    post:
      summary: Wallet transaction signed
      description: Triggered when the `wallet.transaction.signed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionSignedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.signed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionSignedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionBroadcast:
    post:
      summary: Wallet transaction broadcast
      description: Triggered when the `wallet.transaction.broadcast` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionBroadcastWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.broadcast` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionBroadcastEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionReplaced:
    post:
      summary: Wallet transaction replaced
      description: Triggered when the `wallet.transaction.replaced` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionReplacedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.replaced` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionReplacedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionPending:
    post:
      summary: Wallet transaction pending
      description: Triggered when the `wallet.transaction.pending` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionPendingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.pending` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionPendingEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionConfirmed:
    post:
      summary: Wallet transaction confirmed
      description: Triggered when the `wallet.transaction.confirmed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionConfirmedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.confirmed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionConfirmedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTransactionFailed:
    post:
      summary: Wallet transaction failed
      description: Triggered when the `wallet.transaction.failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTransactionFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.transaction.failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransactionFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletDelegationCreated:
    post:
      summary: Wallet delegation created
      description: Triggered when the `wallet.delegation.created` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletDelegationCreatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.delegation.created` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletDelegationCreatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletDelegationRevoked:
    post:
      summary: Wallet delegation revoked
      description: Triggered when the `wallet.delegation.revoked` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletDelegationRevokedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.delegation.revoked` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletDelegationRevokedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletTypedDataSigned:
    post:
      summary: Wallet typed data signed
      description: Triggered when the `wallet.typed_data.signed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletTypedDataSignedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.typed_data.signed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTypedDataSignedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletMessageSigned:
    post:
      summary: Wallet message signed
      description: Triggered when the `wallet.message.signed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletMessageSignedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.message.signed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletMessageSignedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  walletHashSigned:
    post:
      summary: Wallet hash signed
      description: Triggered when the `wallet.hash.signed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: walletHashSignedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Wallet Webhooks
      requestBody:
        description: The `wallet.hash.signed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletHashSignedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersQuoted:
    post:
      summary: Payments transfers quoted
      description: Triggered when the `payments.transfers.quoted` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersQuotedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.quoted` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersQuotedEvent'
            examples:
              account:
                summary: 'Source: Account'
                value:
                  eventID: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
                  eventType: payments.transfers.quoted
                  timestamp: '2025-01-01T00:00:00Z'
                  data:
                    transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    status: quoted
                    createdAt: '2025-01-01T00:00:00Z'
                    expiresAt: '2025-01-01T00:15:00Z'
                    source:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usd
                    sourceAmount: '103.50'
                    sourceAsset: usd
                    target:
                      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                      network: base
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
              onchainAddress:
                summary: 'Source: Onchain address'
                value:
                  eventID: e3f6a9c2-1b4d-4e78-8a2c-6f9b3d5e7a10
                  eventType: payments.transfers.quoted
                  timestamp: '2026-02-10T09:00:00Z'
                  data:
                    transferId: transfer_af5c3d21-7b4e-4a19-9c6f-2d8e1b3a5f70
                    status: quoted
                    createdAt: '2026-02-10T09:00:00Z'
                    expiresAt: '2026-02-10T09:15:00Z'
                    source:
                      address: '0xabc1234567890abcdef1234567890abcdef123456'
                      network: base
                      asset: usdc
                    sourceAmount: '250.00'
                    sourceAsset: usdc
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '250.00'
                    targetAsset: usdc
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersProcessing:
    post:
      summary: Payments transfers processing
      description: Triggered when the `payments.transfers.processing` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersProcessingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.processing` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersProcessingEvent'
            examples:
              account:
                summary: 'Source: Account'
                value:
                  eventID: b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e
                  eventType: payments.transfers.processing
                  timestamp: '2025-01-01T00:01:30Z'
                  data:
                    transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    status: processing
                    createdAt: '2025-01-01T00:00:00Z'
                    source:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usd
                    sourceAmount: '103.50'
                    sourceAsset: usd
                    target:
                      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                      network: base
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
              onchainAddress:
                summary: 'Source: Onchain address'
                value:
                  eventID: 4d8b2f61-9a3c-4e07-8b1d-5c9e2a4f6b83
                  eventType: payments.transfers.processing
                  timestamp: '2026-02-10T09:02:30Z'
                  data:
                    transferId: transfer_af5c3d21-7b4e-4a19-9c6f-2d8e1b3a5f70
                    status: processing
                    createdAt: '2026-02-10T09:00:00Z'
                    source:
                      address: '0xabc1234567890abcdef1234567890abcdef123456'
                      network: base
                      asset: usdc
                    sourceAmount: '250.00'
                    sourceAsset: usdc
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '250.00'
                    targetAsset: usdc
              achDeposit:
                summary: 'Source: ACH deposit'
                value:
                  eventID: d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a
                  eventType: payments.transfers.processing
                  timestamp: '2026-01-21T20:13:30Z'
                  data:
                    transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    status: processing
                    createdAt: '2026-01-21T20:12:46Z'
                    source:
                      currency: usd
                      companyName: A*** C***
                      companyEntryDescription: PAYROLL
                      individualIdentificationNumber: J*** D***
                    sourceAmount: '100.00'
                    sourceAsset: usd
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
                    details:
                      depositDestination:
                        id: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
                    metadata:
                      customer_id: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersCompleted:
    post:
      summary: Payments transfers completed
      description: Triggered when the `payments.transfers.completed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersCompletedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.completed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersCompletedEvent'
            examples:
              account:
                summary: 'Source: Account'
                value:
                  eventID: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  eventType: payments.transfers.completed
                  timestamp: '2025-01-01T00:05:00Z'
                  data:
                    transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    status: completed
                    createdAt: '2025-01-01T00:00:00Z'
                    completedAt: '2025-01-01T00:05:00Z'
                    source:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usd
                    sourceAmount: '103.50'
                    sourceAsset: usd
                    target:
                      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                      network: base
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
              onchainAddress:
                summary: 'Source: Onchain address'
                value:
                  eventID: 7a1c4e9b-2f6d-4318-9b7a-3e5c8d1f4a62
                  eventType: payments.transfers.completed
                  timestamp: '2026-02-10T09:05:10Z'
                  data:
                    transferId: transfer_af5c3d21-7b4e-4a19-9c6f-2d8e1b3a5f70
                    status: completed
                    createdAt: '2026-02-10T09:00:00Z'
                    completedAt: '2026-02-10T09:05:10Z'
                    source:
                      address: '0xabc1234567890abcdef1234567890abcdef123456'
                      network: base
                      asset: usdc
                    sourceAmount: '250.00'
                    sourceAsset: usdc
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '250.00'
                    targetAsset: usdc
              achDeposit:
                summary: 'Source: ACH deposit'
                value:
                  eventID: 4557efb9-391b-4a9d-987d-d263b9d7fd37
                  eventType: payments.transfers.completed
                  timestamp: '2026-01-21T20:15:04Z'
                  data:
                    transferId: transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114
                    status: completed
                    createdAt: '2026-01-21T20:12:46Z'
                    completedAt: '2026-01-21T20:15:04Z'
                    source:
                      currency: usd
                      companyName: A*** C***
                      companyEntryDescription: PAYROLL
                      individualIdentificationNumber: J*** D***
                    sourceAmount: '100.00'
                    sourceAsset: usd
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
                    details:
                      depositDestination:
                        id: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
                    metadata:
                      customer_id: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersFailed:
    post:
      summary: Payments transfers failed
      description: Triggered when the `payments.transfers.failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersFailedEvent'
            examples:
              account:
                summary: 'Source: Account'
                value:
                  eventID: c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f
                  eventType: payments.transfers.failed
                  timestamp: '2025-01-01T00:02:15Z'
                  data:
                    transferId: transfer_bf3a48c1-a957-51ba-8c0f-add33e068447
                    status: failed
                    createdAt: '2025-01-01T00:00:00Z'
                    failureReason: Insufficient balance to complete this transfer.
                    source:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usd
                    sourceAmount: '103.50'
                    sourceAsset: usd
                    target:
                      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                      network: base
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
              onchainAddress:
                summary: 'Source: Onchain address'
                value:
                  eventID: 9f3d6b1a-4c8e-4257-8d2b-1a7f5e9c3b04
                  eventType: payments.transfers.failed
                  timestamp: '2026-02-05T11:33:45Z'
                  data:
                    transferId: transfer_e8f1a3c5-2d4b-4e6a-9c8b-3f5d7a9b1c2e
                    status: failed
                    createdAt: '2026-02-05T11:30:00Z'
                    failureReason: Onchain deposit was reversed after failing compliance screening.
                    source:
                      address: '0xabc1234567890abcdef1234567890abcdef123456'
                      network: base
                      asset: usdc
                    sourceAmount: '75.00'
                    sourceAsset: usdc
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '75.00'
                    targetAsset: usdc
              achDeposit:
                summary: 'Source: ACH deposit'
                value:
                  eventID: e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b
                  eventType: payments.transfers.failed
                  timestamp: '2026-01-20T14:08:30Z'
                  data:
                    transferId: transfer_cf4958d2-b068-62cb-9d12-fee55f268447
                    status: failed
                    createdAt: '2026-01-20T14:05:00Z'
                    failureReason: 'ACH deposit returned: insufficient funds in originating account.'
                    source:
                      currency: usd
                      companyName: A*** C***
                      companyEntryDescription: PAYROLL
                      individualIdentificationNumber: J*** D***
                    sourceAmount: '100.00'
                    sourceAsset: usd
                    target:
                      accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
                      asset: usdc
                    targetAmount: '100.00'
                    targetAsset: usdc
                    details:
                      depositDestination:
                        id: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
                    metadata:
                      customer_id: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersExpired:
    post:
      summary: Payments transfers expired
      description: Triggered when the `payments.transfers.expired` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersExpiredWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.expired` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersExpiredEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersTravelRuleIncomplete:
    post:
      summary: Payments transfers travel rule incomplete
      description: Triggered when the `payments.transfers.travel_rule_incomplete` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersTravelRuleIncompleteWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.travel_rule_incomplete` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersTravelRuleIncompleteEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  paymentsTransfersTravelRuleCompleted:
    post:
      summary: Payments transfers travel rule completed
      description: Triggered when the `payments.transfers.travel_rule_completed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: paymentsTransfersTravelRuleCompletedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Transfers
      requestBody:
        description: The `payments.transfers.travel_rule_completed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentsTransfersTravelRuleCompletedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  onrampTransactionCreated:
    post:
      summary: Onramp transaction created
      description: Triggered when the `onramp.transaction.created` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: onrampTransactionCreatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `onramp.transaction.created` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampTransactionCreatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  onrampTransactionUpdated:
    post:
      summary: Onramp transaction updated
      description: Triggered when the `onramp.transaction.updated` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: onrampTransactionUpdatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `onramp.transaction.updated` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampTransactionUpdatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  onrampTransactionSuccess:
    post:
      summary: Onramp transaction succeeded
      description: Triggered when the `onramp.transaction.success` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: onrampTransactionSuccessWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `onramp.transaction.success` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampTransactionSuccessEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  onrampTransactionFailed:
    post:
      summary: Onramp transaction failed
      description: Triggered when the `onramp.transaction.failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: onrampTransactionFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `onramp.transaction.failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampTransactionFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  offrampTransactionCreated:
    post:
      summary: Offramp transaction created
      description: Triggered when the `offramp.transaction.created` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: offrampTransactionCreatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `offramp.transaction.created` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfframpTransactionCreatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  offrampTransactionUpdated:
    post:
      summary: Offramp transaction updated
      description: Triggered when the `offramp.transaction.updated` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: offrampTransactionUpdatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `offramp.transaction.updated` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfframpTransactionUpdatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  offrampTransactionSuccess:
    post:
      summary: Offramp transaction succeeded
      description: Triggered when the `offramp.transaction.success` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: offrampTransactionSuccessWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `offramp.transaction.success` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfframpTransactionSuccessEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  offrampTransactionFailed:
    post:
      summary: Offramp transaction failed
      description: Triggered when the `offramp.transaction.failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: offrampTransactionFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Onramp
      requestBody:
        description: The `offramp.transaction.failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfframpTransactionFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionCreated:
    post:
      summary: Payment session created
      description: Triggered when the `acceptance.payment_session.created` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionCreatedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.created` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionCreatedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionCanceled:
    post:
      summary: Payment session canceled
      description: Triggered when the `acceptance.payment_session.canceled` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionCanceledWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.canceled` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionCanceledEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionAuthorizationPending:
    post:
      summary: Payment session authorization pending
      description: Triggered when the `acceptance.payment_session.authorization_pending` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionAuthorizationPendingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.authorization_pending` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionAuthorizationPendingEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionAuthorizationSucceeded:
    post:
      summary: Payment session authorization succeeded
      description: Triggered when the `acceptance.payment_session.authorization_succeeded` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionAuthorizationSucceededWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.authorization_succeeded` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionAuthorizationSucceededEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionAuthorizationFailed:
    post:
      summary: Payment session authorization failed
      description: Triggered when the `acceptance.payment_session.authorization_failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionAuthorizationFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.authorization_failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionAuthorizationFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionCapturePending:
    post:
      summary: Payment session capture pending
      description: Triggered when the `acceptance.payment_session.capture_pending` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionCapturePendingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.capture_pending` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionCapturePendingEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionCaptureSucceeded:
    post:
      summary: Payment session capture succeeded
      description: Triggered when the `acceptance.payment_session.capture_succeeded` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionCaptureSucceededWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.capture_succeeded` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionCaptureSucceededEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionCaptureFailed:
    post:
      summary: Payment session capture failed
      description: Triggered when the `acceptance.payment_session.capture_failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionCaptureFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.capture_failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionCaptureFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionRefundPending:
    post:
      summary: Payment session refund pending
      description: Triggered when the `acceptance.payment_session.refund_pending` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionRefundPendingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.refund_pending` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionRefundPendingEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionRefundSucceeded:
    post:
      summary: Payment session refund succeeded
      description: Triggered when the `acceptance.payment_session.refund_succeeded` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionRefundSucceededWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.refund_succeeded` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionRefundSucceededEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionRefundFailed:
    post:
      summary: Payment session refund failed
      description: Triggered when the `acceptance.payment_session.refund_failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionRefundFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.refund_failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionRefundFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionVoidPending:
    post:
      summary: Payment session void pending
      description: Triggered when the `acceptance.payment_session.void_pending` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionVoidPendingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.void_pending` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionVoidPendingEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionVoidSucceeded:
    post:
      summary: Payment session void succeeded
      description: Triggered when the `acceptance.payment_session.void_succeeded` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionVoidSucceededWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.void_succeeded` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionVoidSucceededEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptancePaymentSessionVoidFailed:
    post:
      summary: Payment session void failed
      description: Triggered when the `acceptance.payment_session.void_failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptancePaymentSessionVoidFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Payment Sessions
      requestBody:
        description: The `acceptance.payment_session.void_failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptancePaymentSessionVoidFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptanceDisbursementPending:
    post:
      summary: Disbursement pending
      description: Triggered when the `acceptance.disbursement.pending` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptanceDisbursementPendingWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Disbursements
      requestBody:
        description: The `acceptance.disbursement.pending` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptanceDisbursementPendingEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptanceDisbursementSucceeded:
    post:
      summary: Disbursement succeeded
      description: Triggered when the `acceptance.disbursement.succeeded` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptanceDisbursementSucceededWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Disbursements
      requestBody:
        description: The `acceptance.disbursement.succeeded` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptanceDisbursementSucceededEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  acceptanceDisbursementFailed:
    post:
      summary: Disbursement failed
      description: Triggered when the `acceptance.disbursement.failed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: acceptanceDisbursementFailedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Disbursements
      requestBody:
        description: The `acceptance.disbursement.failed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptanceDisbursementFailedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  customersCapabilityChanged:
    post:
      summary: Customers capability changed
      description: Triggered when the `customers.capability.changed` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: customersCapabilityChangedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Customers
      requestBody:
        description: The `customers.capability.changed` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomersCapabilityChangedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
  customersCustomerDeleted:
    post:
      summary: Customer deleted
      description: Triggered when the `customers.customer.deleted` webhook event is emitted. Your API will receive a POST request at the webhook URL you configured.
      operationId: customersCustomerDeletedWebhook
      security:
        - webhookSignature: []
      x-audience: public
      tags:
        - Customers
      requestBody:
        description: The `customers.customer.deleted` webhook event payload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomersCustomerDeletedEvent'
      responses:
        '200':
          description: Webhook received and processed successfully.
        '401':
          description: Invalid signature.
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.
    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
    XWalletAuth:
      name: X-Wallet-Auth
      in: header
      required: true
      description: |
        A JWT signed using your Wallet Secret, encoded in base64. Refer to the
        [Generate Wallet Token](https://docs.cdp.coinbase.com/api-reference/v2/authentication#2-generate-wallet-token)
        section of our Authentication docs for more details on how to generate your Wallet Token.
      schema:
        type: string
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiZXhwIjoxNzAxOTgwMDAwfQ.HWvMTKmCCTxHaxjvZyLaC6UQ6TV3ErTDWBf7zmdH0Lw
    EndUserUserId:
      name: userId
      in: path
      required: true
      description: The ID of the end user to add the account to.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9-]{1,100}$
      example: e051beeb-7163-4527-a5b6-35e301529ff2
    XWalletAuthOptional:
      name: X-Wallet-Auth
      in: header
      required: false
      description: |
        A JWT signed using your Wallet Secret, encoded in base64. Refer to the
        [Generate Wallet Token](https://docs.cdp.coinbase.com/api-reference/v2/authentication#2-generate-wallet-token)
        section of our Authentication docs for more details on how to generate your Wallet Token.
      schema:
        type: string
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiZXhwIjoxNzAxOTgwMDAwfQ.HWvMTKmCCTxHaxjvZyLaC6UQ6TV3ErTDWBf7zmdH0Lw
    XDeveloperAuth:
      name: X-Developer-Auth
      in: header
      required: false
      description: |
        A JWT signed using your Wallet Secret, encoded in base64. Refer to the
        [Generate Wallet Token](https://docs.cdp.coinbase.com/api-reference/v2/authentication#2-generate-wallet-token)
        section of our Authentication docs for more details on how to generate your Wallet Token.
      schema:
        type: string
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiZXhwIjoxNzAxOTgwMDAwfQ.HWvMTKmCCTxHaxjvZyLaC6UQ6TV3ErTDWBf7zmdH0Lw
    ProjectIDOptional:
      name: projectID
      in: query
      required: false
      description: The ID of the CDP Project. Required for end users authenticated using custom auth (i.e. a non-CDP JWT provider).
      schema:
        type: string
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        example: 8e03978e-40d5-43e8-bc93-6894a57f9324
  schemas:
    AccountType:
      type: string
      description: |-
        The type of the Account.

        - `prime`: a linked Coinbase Prime account.
        - `business`: a linked Coinbase Business account.
        - `cdp`: a CDP-native account created via this API. Used for accounts created on
          behalf of an Entity and for Customer-owned accounts.
      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`.

        * **Customer**: `customer_` - If the Owner is one of your Customers,
          e.g. `customer_af2937b0-9846-4fe7-bfe9-ccc22d935114`. Customer ownership requires the
          Customer to have the `custodyCrypto`, `custodyFiat`, and `custodyStablecoin`
          capabilities enabled.
      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
        - otp_verification_code_invalid
        - otp_verification_destination_mismatch
        - otp_verification_expired
        - otp_verification_invalid
        - otp_verification_not_found
        - otp_verification_required
        - 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
        - payment_session_already_canceled
        - payment_session_already_authorized
        - payment_session_action_pending
        - no_capturable_balance
        - no_voidable_balance
        - no_refundable_balance
        - entity_not_configured_for_payment_acceptance
        - daily_transaction_limit_exceeded
        - daily_amount_limit_exceeded
        - stale_attestation
        - moderation_rejected
      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 `PUT /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

          **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<any>) {
            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<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
            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<T>(
            operation: () => Promise<T>,
            maxRetries = 3,
            timeout = 30000,
          ): Promise<T> {
            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.
        otp_verification_destination_mismatch: |-
          The `phoneNumber` or `email` on the order does not match the `destination` that was verified.

          **Steps to resolve:**
          1. Ensure the `phoneNumber` or `email` field on the order matches the `destination` used during verification.
          2. If the value changed, complete a new verification for the updated phone number or email.
        otp_verification_expired: |-
          The `smsVerificationId` or `emailVerificationId` provided has expired.
          Verification IDs are valid for 60 days after successful OTP submission.

          **Steps to resolve:**
          1. Complete a new verification flow for the user.
          2. Use the new verification ID when creating orders.
        otp_verification_code_invalid: |-
          This error occurs when the OTP code submitted to complete a verification is incorrect or has expired
          (the 10-minute OTP window has elapsed).

          **Steps to resolve:**
          1. Ask the user to re-enter the code.
          2. If the OTP window has expired, start a new verification flow.
        otp_verification_invalid: |-
          This error occurs when the verification record exists but is not in a usable state for the requested operation.

          **Common causes:**
          - The verification is still pending (OTP not yet submitted successfully).
          - The verification has been revoked.
          - The verification channel does not match the expected field (`smsVerificationId` or `emailVerificationId`).

          **Steps to resolve:**
          1. Complete a new verification flow and retry.
        otp_verification_not_found: |-
          The provided SMS or email verification ID does not correspond to any verification record.

          **Steps to resolve:**
          1. Ensure you are passing the correct verification ID as `smsVerificationId` or `emailVerificationId`.
          2. If the issue persists, complete a new verification flow.
        otp_verification_required: |-
          An SMS or email verification ID is required on order creation but none was provided.

          **Steps to resolve:**
          1. Verify the user's phone number and email before creating an order.
          2. Pass the returned verification IDs as `smsVerificationId` and `emailVerificationId` when creating orders.
        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
        payment_session_already_canceled: |-
          This error occurs when an action is attempted on a payment session that has already been canceled.

          **Steps to resolve:**
          1. Create a new payment session to proceed with the payment flow
        payment_session_already_authorized: |-
          This error occurs when attempting to authorize a payment session that has already been authorized.

          **Steps to resolve:**
          1. Check the payment session status — it is already authorized
          2. Proceed to capture, void, or other post-authorization actions as needed
        payment_session_action_pending: |-
          This error occurs when another action is already in progress for the payment session.

          **Steps to resolve:**
          1. Wait for the current action to complete before retrying
          2. Check the payment session status to confirm the current action result
        no_capturable_balance: |-
          This error occurs when there is no remaining balance available to capture on the payment session.

          **Steps to resolve:**
          1. Verify the payment session status and previously captured amounts
          2. Ensure the session was authorized and has uncaptured funds remaining
        no_voidable_balance: |-
          This error occurs when there is no held balance remaining to void on the payment session.

          **Steps to resolve:**
          1. Verify the payment session has an authorized but uncaptured balance
          2. Check whether the session has already been fully captured or voided
        no_refundable_balance: |-
          This error occurs when the payment session has no captured amount available to refund.

          **Steps to resolve:**
          1. Verify the payment session has been previously captured
          2. Check that the session has not already been fully refunded
        entity_not_configured_for_payment_acceptance: |-
          This error occurs when the entity is not configured to accept payments.

          **Steps to resolve:**
          1. Contact support to enable payment acceptance for the entity
        daily_transaction_limit_exceeded: |-
          This error occurs when the daily transaction limit has been exceeded.

          **Steps to resolve:**
          1. Wait until the next day when the daily limit resets
          2. Contact support for questions about your limit
        daily_amount_limit_exceeded: |-
          This error occurs when the daily authorization amount limit has been exceeded.

          **Steps to resolve:**
          1. Wait until the next day when the daily limit resets
          2. Contact support for questions about your limit
        stale_attestation: |-
          The platform attestation (iOS App Attest assertion or Android Play Integrity token) was
          generated against a challenge that has since expired. The request was well-formed, but
          the challenge is no longer valid.

          **Steps to resolve:**
          1. Call [Create Onramp Mobile Challenge](#operation/createOnrampMobileChallenge) to obtain
             a fresh challenge.
          2. Re-run the platform attestation flow against the new challenge.
          3. Submit the new attestation to
             [Create Onramp Mobile Session](#operation/createOnrampMobileSession) promptly —
             challenges are short-lived.

          **Common causes:**
          - Too much time elapsed between obtaining the challenge and submitting the attestation.
        moderation_rejected: |-
          The uploaded image failed content moderation and will not be served.

          **Steps to resolve:**
          1. Upload a different image that complies with content policies.
    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
      x-enum-varnames:
        - 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
    Compliance:
      type: object
      description: |
        Compliance context for a request. Carries per-request compliance signals,
        such as the IP address of the individual (i.e., end-customer) that
        initiated the request.

        This object is request-only — it is never echoed back in responses.
        Inner fields are write-only.
      properties:
        requesterIpAddress:
          type: string
          writeOnly: true
          description: |
            IPv4 or IPv6 address of the individual (i.e., end-customer) that
            initiated this request. NOT the IP of the partner server making the
            API call.
          example: 203.0.113.42
      example:
        requesterIpAddress: 203.0.113.42
    CreateAccountRequest:
      type: object
      properties:
        owner:
          allOf:
            - $ref: '#/components/schemas/Owner'
          description: |-
            The Owner of the Account to create.
            * If omitted, the account will be owned by the Entity making the request.
            * If the account is for a customer, the value will be a Customer ID,
              e.g. `customer_af2937b0-9846-4fe7-bfe9-ccc22d935114`.

            * Further, the corresponding Customer must have all of the following capabilities enabled:
              - `custodyCrypto`
              - `custodyFiat`
              - `custodyStablecoin`.
          example: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
        name:
          $ref: '#/components/schemas/AccountName'
        compliance:
          $ref: '#/components/schemas/Compliance'
          writeOnly: true
    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'
    CustomerId:
      type: string
      pattern: ^customer_[a-f0-9\-]{36}$
      description: The ID of the Customer, which is a UUID prefixed by `customer_`.
      example: customer_af2937b0-9846-4fe7-bfe9-ccc22d935114
    CustomerType:
      type: string
      description: |
        The type of the customer. Required on create; accepted but ignored on update.
      enum:
        - individual
      x-enum-varnames:
        - CustomerTypeIndividual
      example: individual
    CapabilityStatus:
      type: string
      description: |
        The status of a capability. Based on recoverability:
        - `unrequested`: Capability has not been requested by the customer
        - `pending`: Customer can take action to resolve (requirements `due` or `rejected`)
        - `active`: Capability is enabled and can be used
        - `inactive`: Permanently blocked - no customer action possible
      enum:
        - unrequested
        - pending
        - active
        - inactive
      example: active
    Capability:
      type: object
      description: |
        The current state of a capability for a customer. The `status` field is always
        present. When `requested` is `false`, the status will be `unrequested`.
      properties:
        requested:
          type: boolean
          description: Whether the customer has explicitly requested this capability.
          example: true
        status:
          allOf:
            - $ref: '#/components/schemas/CapabilityStatus'
          description: |
            Current status of the capability. When `requested` is `false`, status is `unrequested`.
            When `requested` is `true`, status is one of `pending`, `active`, or `inactive`.
          example: active
      required:
        - requested
        - status
    CapabilitiesMap:
      type: object
      description: |
        The current state of each capability for a Customer. Each capability shows
        whether it has been requested and its current status.
      properties:
        custodyCrypto:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Hold cryptocurrency in a Coinbase custodial account.
        custodyFiat:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Hold fiat currency in a Coinbase custodial account.
        custodyStablecoin:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Hold stablecoin in a Coinbase custodial account.
        tradeCrypto:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Trade cryptocurrency.
        tradeStablecoin:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Trade stablecoin.
        transferCrypto:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Transfer cryptocurrency to another party.
        transferFiat:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Transfer fiat currency to another party.
        transferStablecoin:
          allOf:
            - $ref: '#/components/schemas/Capability'
          description: Transfer stablecoin to another party.
      example:
        custodyCrypto:
          requested: true
          status: active
        custodyFiat:
          requested: false
          status: unrequested
        custodyStablecoin:
          requested: false
          status: unrequested
        tradeCrypto:
          requested: false
          status: unrequested
        tradeStablecoin:
          requested: false
          status: unrequested
        transferCrypto:
          requested: true
          status: active
        transferFiat:
          requested: false
          status: unrequested
        transferStablecoin:
          requested: false
          status: unrequested
    RequirementStatus:
      type: string
      description: |
        The current status of a requirement:
        - `due`: Must be submitted
        - `pending`: Submitted, awaiting verification
        - `rejected`: Verification failed - customer must resubmit

        When verification passes, the requirement disappears from the response entirely.
      enum:
        - due
        - pending
        - rejected
      example: due
    TosVersionId:
      type: string
      minLength: 1
      maxLength: 64
      description: |
        Stable, opaque identifier for a specific Terms of Service version
        (for example, `us_individual_2026-05-29`). The same identifier is
        surfaced on `Customer.requirements.tos.tosVersions[].versionId` (the
        versions a Customer still needs to accept) and on
        `Customer.tosAcceptances[].versionId` (the versions the Customer has
        accepted). Treat the value as opaque and submit it verbatim; the
        identifier format is stable across API versions, but the set of
        valid values grows over time as new Terms of Service versions are
        published.
      example: us_individual_2026-05-29
    TermsOfService:
      type: object
      description: |
        Metadata for one Terms of Service document a Customer may need to
        accept. Each entry represents one logical document (identified by
        `versionId`) that may be published in multiple languages —
        `languages` lists the BCP 47 language tags the document is available
        to view and accept in. `url` is the canonical, language-agnostic
        document URL; partners append `?lang=<tag>` (where `<tag>` is one of
        `languages`) to retrieve a specific translation, and omit the
        parameter to let the documentation site choose a default. This API
        does not serve Terms of Service body content; this schema describes
        metadata only.
      properties:
        versionId:
          allOf:
            - $ref: '#/components/schemas/TosVersionId'
          description: |
            Stable identifier for this Terms of Service document. Submit this
            value as `versionId` on a `TosAcceptance` to record acceptance.
        languages:
          type: array
          description: |
            BCP 47 language tags this Terms of Service document can be viewed
            and accepted in. The list is non-empty (every published document
            carries at least one language). Append the chosen tag to `url` as
            `?lang=<tag>` to fetch the localized document, and submit the same
            tag as `language` on the corresponding `TosAcceptance` to record
            which translation the Customer reviewed.
          minItems: 1
          items:
            type: string
            example: en
          example:
            - en
        url:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: |
            Canonical, language-agnostic URL where the Terms of Service
            document is hosted (for example,
            `https://docs.cdp.coinbase.com/legal/terms/us_individual`).
            Append `?lang=<tag>` (where `<tag>` is one of `languages`) to
            retrieve a specific translation; without the parameter, the
            documentation site renders a default translation.
          example: https://docs.cdp.coinbase.com/legal/terms/us_individual
      required:
        - versionId
        - languages
        - url
      example:
        versionId: us_individual_2026-05-29
        languages:
          - en
        url: https://docs.cdp.coinbase.com/legal/terms/us_individual
    TaxForm:
      type: string
      description: |
        Identifier for a tax attestation form a Customer may need to
        complete. The same identifier is surfaced on
        `Customer.requirements.taxAttestation.taxForms[]` (the forms a
        Customer still needs to attest to) and submitted back as `form` on
        `Customer.taxAttestations[]` to record the attestation.
      enum:
        - us_w9
      example: us_w9
    Requirement:
      type: object
      description: |
        A single requirement that a customer must submit to enable capabilities.
        Requirements are only shown for requested capabilities.
      properties:
        status:
          $ref: '#/components/schemas/RequirementStatus'
        deadline:
          type: string
          format: date-time
          description: |
            Optional deadline by which this requirement must be satisfied.

            For the `tos` requirement, when present, `deadline` is the earliest
            deadline among the unaccepted required Terms of Service versions.
        impact:
          type: array
          description: |
            List of capabilities affected by this requirement, sorted alphabetically.
            Only present for `due`, `pending`, or `rejected` statuses.
          items:
            $ref: '#/components/schemas/CapabilityName'
          example:
            - custodyCrypto
            - transferCrypto
        tosVersions:
          type: array
          description: |
            Required Terms of Service versions the Customer has not yet
            accepted, with the metadata needed to render an acceptance UI
            (each entry carries a stable `versionId`, the BCP 47
            `languages` the version is published in, and a
            language-agnostic `url`). This field appears only under the
            requirement key `tos`; do not infer meaning from `tosVersions`
            on other requirement keys. Only populated for the `tos`
            requirement; omitted on every other requirement key. Submit each
            `versionId` back via `tosAcceptances[].versionId` on `Update Customer` (or
            `Create Customer`) together with `language` and `acceptedAt` to clear the requirement.
          items:
            $ref: '#/components/schemas/TermsOfService'
          example:
            - versionId: us_individual_2026-05-29
              languages:
                - en
              url: https://docs.cdp.coinbase.com/legal/terms/us_individual
        taxForms:
          type: array
          description: |
            Required tax attestation forms the Customer has not yet completed.
            This field appears only under the requirement key `taxAttestation`.
            Submit each `form` back via `taxAttestations[].form` on
            `Update Customer` (or `Create Customer`) together with the other
            fields required for that form to clear the requirement.
          items:
            $ref: '#/components/schemas/TaxForm'
          example:
            - us_w9
      required:
        - status
      example:
        status: due
        impact:
          - custodyCrypto
          - transferCrypto
    RequirementsMap:
      type: object
      description: |
        Map of requirements to be submitted. Each key is the field name
        (e.g., "ssnLast4"), with values to describe its state. Requirements
        are only shown for requested capabilities. When a requirement is
        verified, it disappears from this map.

        When comparing deadlines across keys, note that `requirements.tos.deadline`
        is an aggregate: the earliest deadline among unaccepted required Terms of
        Service versions listed in `requirements.tos.tosVersions[]` (not a separate
        clock from those version rows).
      additionalProperties:
        $ref: '#/components/schemas/Requirement'
      example:
        firstName:
          status: due
          impact:
            - custodyCrypto
            - transferCrypto
        fullSsn:
          status: rejected
          impact:
            - custodyCrypto
        ssnLast4:
          status: pending
          impact:
            - custodyCrypto
        sourceOfFunds:
          status: due
        citizenship:
          status: due
        tos:
          status: due
          impact:
            - transferFiat
          tosVersions:
            - versionId: us_individual_2026-05-29
              languages:
                - en
              url: https://docs.cdp.coinbase.com/legal/terms/us_individual
        taxAttestation:
          status: due
          impact:
            - transferFiat
          taxForms:
            - us_w9
    Email:
      type: string
      format: email
      maxLength: 254
      pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}/-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$
      description: An email address. Maximum length 254 characters per [RFC 5321](https://www.rfc-editor.org/rfc/rfc5321).
      example: user@example.com
    Individual:
      type: object
      description: |
        Individual customer data returned on read — the `individual` object on
        Get / Create / Update Customer responses. Only contact-identity fields are
        echoed back; every other field accepted on the `IndividualInput` object
        (`address`, `ssnLast4`, `dateOfBirth`, `fullSsn`, `citizenship`,
        `phoneNumber`, and the CDD fields) is ingestion-only and never returned.
      properties:
        firstName:
          type: string
          description: First name (given name).
          example: Jane
        lastName:
          type: string
          description: Last name (family name/surname).
          example: Doe
        email:
          allOf:
            - $ref: '#/components/schemas/Email'
          description: Email address for the customer.
          example: jane.doe@example.com
      example:
        firstName: Jane
        lastName: Doe
        email: jane.doe@example.com
    ProjectId:
      type: string
      format: uuid
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      description: The ID of the Project, a UUID v4.
      example: af2937b0-9846-4fe7-bfe9-ccc22d935114
    TosAcceptance:
      type: object
      description: |
        A single Terms of Service acceptance recorded for a Customer. Submit
        one entry per required document listed in
        `Customer.requirements.tos.tosVersions[]` (returned on `Get Customer`,
        `Create Customer`, and `Update Customer`). `language` records the
        single translation the Customer actually reviewed.

        When new required Terms of Service versions are published, only the
        new `versionId`s appear in `Customer.requirements.tos.tosVersions[]`;
        submit acceptances for only those new version(s).
      additionalProperties: false
      properties:
        versionId:
          allOf:
            - $ref: '#/components/schemas/TosVersionId'
          description: |
            The `versionId` of the Terms of Service document being accepted,
            as listed in `Customer.requirements.tos.tosVersions[]`.
        language:
          type: string
          description: |
            BCP 47 language tag of the Terms of Service translation the
            Customer reviewed. At write time the server rejects values that
            are not listed under `languages` on the matching required
            document for this Customer (same `versionId` as listed in
            `Customer.requirements.tos.tosVersions[]`).
          example: en
        acceptedAt:
          type: string
          format: date-time
          description: |
            Timestamp at which the Customer accepted the Terms of Service,
            in ISO 8601 / RFC 3339 format. The server may validate or reject
            obviously non-credible timestamps; when enforcement tightens,
            the authoritative acceptance time may be recorded server-side
            instead of trusting client-supplied values alone.
          example: '2026-04-10T12:00:00Z'
      required:
        - versionId
        - language
        - acceptedAt
      example:
        versionId: us_individual_2026-05-29
        language: en
        acceptedAt: '2026-04-10T12:00:00Z'
    Customer:
      type: object
      description: A customer record returned on read (Get / Create / Update Customer).
      properties:
        customerId:
          $ref: '#/components/schemas/CustomerId'
        type:
          $ref: '#/components/schemas/CustomerType'
        capabilities:
          allOf:
            - $ref: '#/components/schemas/CapabilitiesMap'
          description: |
            Current state of each capability for this customer. Each capability
            shows whether it has been requested and its current status.
          readOnly: true
          example: {}
        requirements:
          allOf:
            - $ref: '#/components/schemas/RequirementsMap'
          description: |
            Map of requirements to be submitted. Each key is the field name, with
            values to describe its state. Requirements are only shown for requested
            capabilities. When a requirement is fulfilled, it disappears from this map.
          readOnly: true
          example: {}
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the customer was created.
          example: '2026-01-10T14:25:00Z'
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the customer was last updated.
          example: '2026-01-10T14:30:00Z'
          readOnly: true
        individual:
          $ref: '#/components/schemas/Individual'
        projectIds:
          type: array
          description: The project IDs that this customer is associated with.
          items:
            $ref: '#/components/schemas/ProjectId'
          example: []
        tosAcceptances:
          type: array
          description: |
            Terms of Service acceptances recorded for the customer.
          items:
            $ref: '#/components/schemas/TosAcceptance'
          example:
            - versionId: us_individual_2026-05-29
              language: en
              acceptedAt: '2026-04-10T12:00:00Z'
      required:
        - customerId
        - type
        - capabilities
        - requirements
    CapabilityInput:
      type: object
      description: Request to enable or disable a capability.
      additionalProperties: false
      properties:
        requested:
          type: boolean
          description: Whether to request this capability.
          example: true
      required:
        - requested
    CapabilitiesMapInput:
      type: object
      description: |
        The capabilities to request for a Customer. Each capability can be
        individually requested. The requirements to enable each capability
        will be returned in the response.
      additionalProperties: false
      properties:
        custodyCrypto:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Hold cryptocurrency in a Coinbase custodial account.
        custodyFiat:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Hold fiat currency in a Coinbase custodial account.
        custodyStablecoin:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Hold stablecoin in a Coinbase custodial account.
        tradeCrypto:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Trade cryptocurrency.
        tradeStablecoin:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Trade stablecoin.
        transferCrypto:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Transfer cryptocurrency to another party.
        transferFiat:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Transfer fiat currency to another party.
        transferStablecoin:
          allOf:
            - $ref: '#/components/schemas/CapabilityInput'
          description: Transfer stablecoin to another party.
      example:
        custodyCrypto:
          requested: true
        transferCrypto:
          requested: true
    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
    DateOfBirthLenient:
      type: object
      description: |
        Date of birth with lenient formatting. Accepts both zero-padded ("04", "07")
        and single-digit ("4", "7") values for day and month.
      additionalProperties: false
      properties:
        day:
          type: string
          description: Day of birth (1-31). Both single-digit ("7") and zero-padded ("07") formats are accepted.
          minLength: 1
          maxLength: 2
          pattern: ^(?:0?[1-9]|[12][0-9]|3[01])$
          example: '15'
        month:
          type: string
          description: Month of birth (1-12). Both single-digit ("4") and zero-padded ("04") formats are accepted.
          minLength: 1
          maxLength: 2
          pattern: ^(?:0?[1-9]|1[0-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'
    CountryCode:
      type: string
      minLength: 2
      maxLength: 2
      pattern: ^[A-Z]{2}$
      description: An ISO 3166-1 alpha-2 country code.
      example: US
    PhoneNumber:
      type: string
      pattern: ^\+[1-9]\d{1,14}$
      description: A phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
      example: '+12055555555'
    IndividualInput:
      type: object
      description: |
        Individual customer data submitted on create / update requests. Fields are
        organized by the capabilities they unlock; not all are required for all
        customers (the requirements depend on which capabilities are requested).
        Read responses return the narrower `Individual` object (only `firstName`,
        `lastName`, and `email`), not this full request shape.
      additionalProperties: false
      properties:
        firstName:
          type: string
          description: First name (given name).
          example: Jane
        lastName:
          type: string
          description: Last name (family name/surname).
          example: Doe
        address:
          allOf:
            - $ref: '#/components/schemas/PhysicalAddress'
            - type: object
              properties:
                countryCode:
                  description: |
                    ISO 3166-1 alpha-2 country code. Only US addresses
                    are currently supported.
                  enum:
                    - US
          description: |
            Primary residential address. Only US addresses are currently
            supported. Non-US `countryCode` values are rejected with a 400.
        ssnLast4:
          type: string
          description: |
            Last 4 digits of the Social Security Number (US only).
            Used for identity verification.
          minLength: 4
          maxLength: 4
          pattern: ^[0-9]{4}$
          example: '6789'
        dateOfBirth:
          allOf:
            - $ref: '#/components/schemas/DateOfBirthLenient'
          description: Date of birth.
        fullSsn:
          type: string
          description: |
            Full Social Security Number (US only).
          pattern: ^([0-9]{3}-[0-9]{2}-[0-9]{4}|\*\*\*-\*\*-[0-9]{4})$
          example: '***-**-6789'
        citizenship:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          description: |
            ISO 3166-1 alpha-2 country code representing the customer's citizenship.
        email:
          allOf:
            - $ref: '#/components/schemas/Email'
          description: Email address for the customer.
          example: jane.doe@example.com
        phoneNumber:
          allOf:
            - $ref: '#/components/schemas/PhoneNumber'
          description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
          example: '+15551234567'
        purposeOfAccount:
          type: string
          description: |
            Primary purpose for using Coinbase services.
          enum:
            - investing
            - long_term_investment
            - short_term_investment
            - trading
            - trading_on_coinbase
            - trading_on_other_exchanges
            - day_trading
            - arbitrage_trading
            - online_purchases
            - online_payments
            - payments_or_gifts
            - payments_to_friends
            - transfer_crypto
            - investing_on_other_exchanges
            - business
            - other
          example: investing
        sourceOfFunds:
          type: string
          description: |
            Primary source of funds for the account.
          enum:
            - salary
            - employment_business_income
            - investments
            - savings
            - pension
            - business_earnings
            - crypto_assets
            - inheritance
            - sale_of_assets
            - sale_of_company_shares_or_dividends
            - sale_of_property
            - sale_of_other_assets
            - credit_or_loan
            - government_benefits_or_credits
            - legal_settlement
            - family_or_third_party
            - lottery_or_gambling
            - crypto_mining
            - other
          example: salary
        employmentStatus:
          type: string
          description: |
            Current employment status.
          enum:
            - employed_fulltime
            - employed_parttime
            - self_employed
            - employed_government_official
            - employed_company_officer_or_board_member
            - employed_crypto_related_business
            - personal_trader_or_angel_investor
            - crypto_miner
            - student
            - retired
            - homemaker
            - unemployed
            - dependent
          example: employed_fulltime
        occupation:
          type: string
          description: |
            Industry or occupation.
          enum:
            - agriculture
            - arts_and_media
            - casinos_and_gaming
            - construction
            - cryptocurrency
            - defense
            - education
            - energy_oil_and_gas
            - energy_other
            - entertainment
            - finance
            - financial_services_non_crypto
            - fintech_non_crypto_software_development
            - fintech_non_crypto_internet_only_financial_institution
            - fintech_non_crypto_other
            - food_and_hospitality
            - government
            - health_and_fitness
            - healthcare
            - healthcare_other
            - healthcare_pharmaceuticals
            - mining
            - mining_crypto
            - non_profit_and_charity
            - pharma_industry
            - politics
            - professional_services
            - property_and_construction_building_work
            - property_and_construction_commercial_and_management
            - property_and_construction_design
            - real_estate
            - retail_fashion
            - retail_food_and_beverage
            - retail_jewelry_and_antiques
            - retail_other
            - retail_pharmacy
            - technology
            - technology_and_it
            - transportation
            - all_other_industries_and_services
            - dependent_student_unemployed
            - other
          example: technology
        expectedVolume:
          type: string
          description: |
            Expected annual volume of activity on the account, expressed as a
            dollar range. Use the dollar-honest ids below:

            - `under_1k`: $0 – $1,000
            - `1k_to_10k`: $1,000 – $10,000
            - `10k_to_100k`: $10,000 – $100,000
            - `100k_to_250k`: $100,000 – $250,000
            - `250k_to_750k`: $250,000 – $750,000
            - `750k_to_1_5m`: $750,000 – $1.5M
            - `1_5m_plus`: $1.5M+
          enum:
            - under_1k
            - 1k_to_10k
            - 10k_to_100k
            - 100k_to_250k
            - 250k_to_750k
            - 750k_to_1_5m
            - 1_5m_plus
          example: under_1k
      example:
        firstName: Jane
        lastName: Doe
        address:
          line1: 500 Main St
          city: Boston
          state: MA
          postCode: '02108'
          countryCode: US
        ssnLast4: '6789'
        dateOfBirth:
          day: '15'
          month: '08'
          year: '1990'
        email: jane.doe@example.com
        phoneNumber: '+15551234567'
    UsW9Attestation:
      type: object
      title: IRS Form W-9
      description: |
        Tax attestation for IRS Form W-9, used for US persons. Carries the
        W-9-specific backup withholding certification alongside the fields common
        to every form (`edeliveryConsent`, `acceptedAt`).
      additionalProperties: false
      properties:
        form:
          type: string
          description: |
            The tax form being attested to, as listed in
            `Customer.requirements.taxAttestation.taxForms[]`. Must be `us_w9`
            for this variant.
          enum:
            - us_w9
          example: us_w9
        edeliveryConsent:
          type: boolean
          description: |
            Whether the Customer consents to electronic delivery (e-delivery) of
            tax documents. Both `true` and `false` are recorded as submitted.
          example: true
        acceptedAt:
          type: string
          format: date-time
          description: |
            Timestamp at which the Customer completed the tax attestation, in
            ISO 8601 / RFC 3339 format. The server may reject obviously
            non-credible timestamps.
          example: '2026-04-17T20:00:00Z'
        isExemptBackupWithholding:
          type: boolean
          description: |
            Whether the Customer is exempt from backup withholding, as certified
            on IRS Form W-9.
          example: true
      required:
        - form
        - edeliveryConsent
        - acceptedAt
        - isExemptBackupWithholding
      example:
        form: us_w9
        isExemptBackupWithholding: true
        edeliveryConsent: true
        acceptedAt: '2026-04-17T20:00:00Z'
    TaxAttestation:
      description: |
        A single tax attestation recorded for a Customer. Submit one entry per
        required form listed in `Customer.requirements.taxAttestation.taxForms[]`
        (returned on `Get Customer`, `Create Customer`, and `Update Customer`
        whenever a `taxAttestation` requirement is unsatisfied). The `form` field
        selects the variant and determines which additional fields are required.
      oneOf:
        - $ref: '#/components/schemas/UsW9Attestation'
      discriminator:
        propertyName: form
        mapping:
          us_w9: '#/components/schemas/UsW9Attestation'
    CustomerWriteBase:
      type: object
      description: |
        Fields accepted on customer create and update requests. Shared by
        `CreateCustomerRequest` and `UpdateCustomerRequest`; excludes the
        server-managed response-only fields that appear on `Customer`.
      additionalProperties: false
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/CustomerType'
          description: |
            The type of the customer. Required on create; accepted but ignored on
            update.
          example: individual
        capabilities:
          allOf:
            - $ref: '#/components/schemas/CapabilitiesMapInput'
          description: Capabilities to request for the customer.
          example: {}
        individual:
          allOf:
            - $ref: '#/components/schemas/IndividualInput'
          description: |
            Information about an Individual customer. Not all fields are required
            for all customers; the requirements depend on which capabilities are
            requested. Submit only fields that are required by the capabilities
            that have been requested.
          example:
            firstName: Jane
            lastName: Doe
        projectIds:
          type: array
          description: The project IDs that this customer is associated with.
          items:
            $ref: '#/components/schemas/ProjectId'
          example: []
        tosAcceptances:
          type: array
          description: |
            Terms of Service acceptances to record on the customer. Submit one
            entry per required version surfaced inline on
            `requirements.tos.tosVersions[]` (returned by `Get Customer`,
            `Create Customer`, and `Update Customer` whenever a `tos` requirement
            is unsatisfied). The server rejects each acceptance whose `language`
            is not listed under `languages` on the matching required version with
            `errorType: "unsupported_tos_language"`.

            When new required Terms of Service versions are published, only the
            new `versionId`s appear in `requirements.tos.tosVersions[]`; submit
            acceptances for only those new version(s).

            Omit `tosAcceptances` on a partial update to leave previously recorded
            acceptances unchanged. Sending `tosAcceptances: []` is invalid
            (`errorType: "invalid_request"`) because it would clear all acceptances
            without replacing them; omit the field entirely when you are not
            updating Terms of Service acceptances.
          items:
            $ref: '#/components/schemas/TosAcceptance'
          example:
            - versionId: us_individual_2026-05-29
              language: en
              acceptedAt: '2026-04-10T12:00:00Z'
        taxAttestations:
          type: array
          writeOnly: true
          description: |
            Tax attestations to record on the customer. Submit one entry per
            required form surfaced inline on
            `requirements.taxAttestation.taxForms[]` (returned by `Get Customer`,
            `Create Customer`, and `Update Customer` whenever a `taxAttestation`
            requirement is unsatisfied). The required fields per entry depend on
            `form`; see `TaxAttestation`. This field is ingestion-only and is
            never returned on read.

            Omit `taxAttestations` on a partial update to leave previously
            recorded attestations unchanged. Sending `taxAttestations: []` is
            invalid (`errorType: "invalid_request"`) because it would clear all
            attestations without replacing them; omit the field entirely when you
            are not updating tax attestations.
          items:
            $ref: '#/components/schemas/TaxAttestation'
          example:
            - form: us_w9
              isExemptBackupWithholding: true
              edeliveryConsent: true
              acceptedAt: '2026-04-17T20:00:00Z'
        compliance:
          $ref: '#/components/schemas/Compliance'
          writeOnly: true
    CreateCustomerRequest:
      allOf:
        - $ref: '#/components/schemas/CustomerWriteBase'
        - type: object
          required:
            - type
    UpdateCustomerRequest:
      allOf:
        - $ref: '#/components/schemas/CustomerWriteBase'
    DepositDestinationType:
      type: string
      description: The type of deposit destination.
      oneOf:
        - title: Crypto
          type: string
          enum:
            - crypto
        - title: Fiat
          type: string
          enum:
            - fiat
      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
    PaymentNetwork:
      type: string
      description: The blockchain network for crypto payments, transfers, and deposit destinations.
      enum:
        - base
        - ethereum
        - solana
        - arbitrum
        - optimism
        - monad
        - sui
        - avacchain
      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/PaymentNetwork'
        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
    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/PaymentNetwork'
        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. Supported values are `usdc` and `eurc`.
          example: usdc
      required:
        - address
        - network
        - asset
      example:
        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        network: base
        asset: usdc
    DepositDestinationTargetOnchainAddress:
      x-audience: public
      title: Target Onchain Address
      description: Routes deposited funds to an external onchain address.
      allOf:
        - $ref: '#/components/schemas/OnchainAddress'
      example:
        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        network: base
        asset: usdc
    DepositDestinationTarget:
      description: The intended target for deposited funds.
      oneOf:
        - $ref: '#/components/schemas/DepositDestinationTargetAccount'
        - $ref: '#/components/schemas/DepositDestinationTargetOnchainAddress'
    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:
      title: Crypto
      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'
    DepositDestinationPaymentRail:
      type: string
      description: A payment rail supported by a fiat deposit destination.
      enum:
        - ach
        - fedwire
      example: ach
    BankAccountUS:
      type: object
      description: A US bank account identified by ABA routing number and account number.
      properties:
        accountType:
          type: string
          description: The type of bank account, based on the account identification scheme (e.g., `us_bank`).
          enum:
            - us_bank
          example: us_bank
        currency:
          type: string
          description: The fiat currency for the deposit destination.
          enum:
            - usd
          example: usd
        bankName:
          type: string
          description: The name of the bank holding the account.
          example: Citibank, N.A.
        beneficiaryName:
          type: string
          description: The name of the account beneficiary.
          example: John Smith
        routingNumber:
          type: string
          description: The ABA routing number of the bank.
          pattern: ^[0-9]{9}$
          example: '987654321'
        accountNumber:
          type: string
          description: The bank account number.
          pattern: ^[0-9]{4,17}$
          example: '123456789'
        bankAddress:
          type: string
          description: The address of the bank. Present when required by the receiving institution.
          example: 399 Park Avenue, New York, NY 10022
        referenceCode:
          type: string
          description: A reference code that must be included in the payment memo or reference field so the receiving institution can route the deposit to the correct account. Only present when required by the receiving institution.
          example: CBAUSD1A2B3C4D
        supportedRails:
          type: array
          description: The payment rails this account can receive deposits on.
          items:
            $ref: '#/components/schemas/DepositDestinationPaymentRail'
          example:
            - ach
      required:
        - accountType
        - currency
        - bankName
        - beneficiaryName
        - routingNumber
        - accountNumber
        - supportedRails
      example:
        accountType: us_bank
        currency: usd
        bankName: Citibank, N.A.
        beneficiaryName: John Smith
        routingNumber: '987654321'
        accountNumber: '123456789'
        bankAddress: 399 Park Avenue, New York, NY 10022
        supportedRails:
          - ach
    DepositDestinationFiat:
      x-audience: public
      description: Fiat bank account details for a deposit destination. The `accountType` field indicates the account identification scheme and determines which fields are present.
      oneOf:
        - $ref: '#/components/schemas/BankAccountUS'
      discriminator:
        propertyName: accountType
        mapping:
          us_bank: '#/components/schemas/BankAccountUS'
    FiatDepositDestination:
      title: Fiat
      x-audience: public
      type: object
      description: A fiat deposit destination. Represents a single bank account provisioned at a single banking partner. Each deposit destination has one status and one lifecycle. The `fiat` object contains the bank account details, keyed by account type.
      properties:
        depositDestinationId:
          $ref: '#/components/schemas/DepositDestinationId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        type:
          type: string
          description: The type of deposit destination.
          enum:
            - fiat
          example: fiat
        fiat:
          $ref: '#/components/schemas/DepositDestinationFiat'
        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: '2025-06-01T00:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the deposit destination was last updated.
          example: '2025-06-01T00:00:00Z'
      required:
        - depositDestinationId
        - accountId
        - type
        - fiat
        - status
        - createdAt
        - updatedAt
      example:
        depositDestinationId: depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336
        accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
        type: fiat
        status: pending
        fiat:
          accountType: us_bank
          currency: usd
          bankName: Citibank, N.A.
          beneficiaryName: John Smith
          routingNumber: '987654321'
          accountNumber: '123456789'
          bankAddress: 399 Park Avenue, New York, NY 10022
          supportedRails:
            - ach
        target:
          accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
          asset: usdc
        metadata:
          customer_id: 123e4567-e89b-12d3-a456-426614174000
          reference: order-12345
        createdAt: '2025-06-01T00:00:00Z'
        updatedAt: '2025-06-01T00:00:00Z'
    DepositDestination:
      description: A deposit destination for receiving funds to an account.
      oneOf:
        - $ref: '#/components/schemas/CryptoDepositDestination'
        - $ref: '#/components/schemas/FiatDepositDestination'
      discriminator:
        propertyName: type
        mapping:
          crypto: '#/components/schemas/CryptoDepositDestination'
          fiat: '#/components/schemas/FiatDepositDestination'
    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'
        compliance:
          $ref: '#/components/schemas/Compliance'
          writeOnly: true
      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/PaymentNetwork'
      required:
        - network
      example:
        network: base
    CreateCryptoDepositDestinationRequest:
      title: Crypto
      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
    CreateDepositDestinationFiat:
      x-audience: public
      type: object
      description: Fiat-specific request fields for creating a deposit destination. The server determines the account type and provisioning method based on the account's eligibility. Optionally specify a `paymentRail` to target a specific payment rail, which may influence banking partner selection.
      properties:
        currency:
          type: string
          description: The fiat currency for the deposit destination.
          enum:
            - usd
          example: usd
        paymentRail:
          allOf:
            - $ref: '#/components/schemas/DepositDestinationPaymentRail'
          description: Optional. The desired payment rail. When omitted, the server provisions the default banking partner and returns all rails the account supports. When specified, the server selects a banking partner that supports the requested rail.
      required:
        - currency
      example:
        currency: usd
    CreateFiatDepositDestinationRequest:
      title: Fiat
      x-audience: public
      allOf:
        - $ref: '#/components/schemas/CreateDepositDestinationRequestBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - fiat
            fiat:
              allOf:
                - $ref: '#/components/schemas/CreateDepositDestinationFiat'
              description: Fiat-specific details. Required when `type` is `fiat`.
          required:
            - fiat
      example:
        accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
        type: fiat
        fiat:
          currency: usd
          paymentRail: ach
        target:
          accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
          asset: usdc
        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'
          fiat: '#/components/schemas/CreateFiatDepositDestinationRequest'
      oneOf:
        - $ref: '#/components/schemas/CreateCryptoDepositDestinationRequest'
        - $ref: '#/components/schemas/CreateFiatDepositDestinationRequest'
    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.
    transfers_Account:
      type: object
      title: Account
      description: The Account specific details for the transfer.
      properties:
        accountId:
          allOf:
            - $ref: '#/components/schemas/AccountId'
          description: The ID of the Account.
        asset:
          allOf:
            - $ref: '#/components/schemas/Asset'
          description: The asset symbol. Supported values are `usdc`, `eurc`, `usd`, and `eur`.
          example: usdc
      required:
        - accountId
        - asset
      example:
        accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
        asset: usdc
    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
    PaymentMethod:
      type: object
      title: Payment Method
      description: The Payment Method specific details for the transfer.
      properties:
        paymentMethodId:
          allOf:
            - $ref: '#/components/schemas/PaymentMethodId'
          description: The ID of the Payment Method.
          example: paymentMethod_af2937b0-9846-4fe7-bfe9-ccc22d935114
        asset:
          allOf:
            - $ref: '#/components/schemas/Asset'
          description: The asset symbol. Supported values are `usd` and `eur`.
          example: usd
      required:
        - paymentMethodId
        - asset
      example:
        paymentMethodId: paymentMethod_af2937b0-9846-4fe7-bfe9-ccc22d935114
        asset: usd
    AchDepositSource:
      x-audience: public
      type: object
      title: ACH Deposit Source
      description: The originating ACH deposit details for the transfer source. Present when funds were deposited via ACH into a deposit destination.
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/Asset'
          description: The fiat currency of the ACH deposit (e.g., `usd`).
          example: usd
        companyName:
          type: string
          maxLength: 16
          description: The company name from the ACH batch header record. Masked on webhook payloads.
          example: Acme Corp
        companyEntryDescription:
          type: string
          maxLength: 10
          description: The company entry description from the ACH batch header record.
          example: PAYROLL
        individualIdentificationNumber:
          type: string
          maxLength: 15
          description: The individual identification number from the ACH entry detail record. For Person-to-Person WEB credit Entries, this field is required and contains the name of the consumer Originator. Masked on webhook payloads.
          example: JANE DOE
      required:
        - currency
        - companyName
        - companyEntryDescription
      example:
        currency: usd
        companyName: Acme Corp
        companyEntryDescription: PAYROLL
        individualIdentificationNumber: JANE DOE
    FedwireDepositSource:
      x-audience: public
      type: object
      title: Fedwire Deposit Source
      description: The originating Fedwire deposit details for the transfer source. Present when funds were deposited via Fedwire into a deposit destination.
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/Asset'
          description: The fiat currency of the Fedwire deposit (e.g., `usd`).
          example: usd
        omad:
          type: string
          maxLength: 22
          description: The Output Message Accountability Data (OMAD), a unique identifier assigned by the Fedwire network to the wire transfer message.
          example: 20240101MMQFMP2P000001
        accountNumber:
          type: string
          pattern: ^[0-9]{4,17}$
          description: The originator's bank account number. Masked on webhook payloads.
          example: '89770098'
        originatorName:
          type: string
          maxLength: 35
          description: The name of the originator. Masked on webhook payloads.
          example: Acme Corp
        originatorToBeneficiary:
          type: array
          description: The Originator to Beneficiary Information (OBI) lines from the Fedwire message. Up to 4 lines, each up to 35 characters. Free-form and may contain identifying information about the originator. Masked on webhook payloads.
          items:
            type: string
            maxLength: 35
          maxItems: 4
          example:
            - Invoice 1234
            - Payment for services rendered
      required:
        - currency
        - omad
        - accountNumber
        - originatorName
      example:
        currency: usd
        omad: 20240101MMQFMP2P000001
        accountNumber: '89770098'
        originatorName: Acme Corp
        originatorToBeneficiary:
          - Invoice 1234
          - Payment for services rendered
    TransferSource:
      description: The source of the transfer.
      oneOf:
        - $ref: '#/components/schemas/transfers_Account'
        - $ref: '#/components/schemas/PaymentMethod'
        - $ref: '#/components/schemas/OnchainAddress'
        - $ref: '#/components/schemas/AchDepositSource'
        - $ref: '#/components/schemas/FedwireDepositSource'
      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: |-
        Captures estimated values for transfers where amounts can't be guaranteed (e.g., USDC -> EURC).

        The values in `estimate` are not modified after a transfer is executed. They are preserved as an immutable record of the original pre-execution snapshot.

        The actual executed values are populated in the `transfer` resource post-execution.
      properties:
        exchangeRate:
          $ref: '#/components/schemas/TransferExchangeRate'
          description: The estimated exchange rate at the time this estimate was captured.
        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'
          description: The estimated fees at the time this estimate was captured.
        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/PaymentNetwork'
            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 received, as a decimal string in standard unit denomination. May be omitted in the `quoted` state if the value cannot be guaranteed; see `estimate.targetAmount` for the expected value. Populated with the actual executed amount once the transfer completes.
          example: '100.00'
        targetAsset:
          allOf:
            - $ref: '#/components/schemas/Asset'
          description: The asset symbol of the target amount.
          example: usdc
        exchangeRate:
          $ref: '#/components/schemas/TransferExchangeRate'
          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. May be omitted in the `quoted` state if the rate cannot be guaranteed; see `estimate.exchangeRate` for the expected rate. Populated with the actual executed rate once the transfer completes.
        fees:
          $ref: '#/components/schemas/TransferFees'
          description: The fees associated with this transfer. Different transfer types have different fee structures. May be omitted in the `quoted` state if the fees cannot be guaranteed; see `estimate.fees` for the expected fees. Populated with the actual fees once the transfer completes.
        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'
      example: {}
    PositiveDecimal:
      type: string
      pattern: ^\+?(?:(?:0*[1-9]\d*)(?:\.\d*)?|0*\.\d*[1-9]\d*)$
      description: A positive decimal string without scientific notation or whitespace.
      example: '100.00'
    IsIntermediary:
      type: boolean
      description: |
        Indicates whether **Coinbase is acting as the intermediary Virtual Asset Service Provider (VASP)**, and your organization is acting as an originating VASP on behalf of your own end customer.

        **Background:**

        The Travel Rule (FATF Recommendation 16) requires VASPs to collect and share certain information about virtual asset transfers. If your organization is a VASP, and you are acting on behalf of your end customer, you must provide additional Travel Rule data to satisfy compliance requirements.

        **Set to `true` when** your organization is itself a VASP acting on behalf of your own end customer (the true originator).

        **Set to `false` (or omit) when** your organization is not itself a VASP acting on behalf of an end customer — for example, if the virtual assets involved are your organization's own funds.

        **Impact on required fields:**

        When `isIntermediary` is `true`, you must provide the `originator` object with the following details:
        - The originator's (i.e. your end customer's) name
        - The originator's address
        - Your organization's VASP information (`virtualAssetServiceProvider` object with `identifier`, `name`, and `address`)

        In certain jurisdictions, `personalId` and `dateOfBirth` must also reflect the **original sender's** identity — not your organization's. These fields will not be auto-populated from any internal KYC data when `isIntermediary` is `true`.
      example: true
    TravelRuleParty:
      type: object
      description: Information about a party (originator or beneficiary) for travel rule compliance.
      properties:
        name:
          type: string
          description: Full name of the party.
          example: John Doe
        address:
          $ref: '#/components/schemas/PhysicalAddress'
        financialInstitution:
          type: string
          description: Name of the financial institution.
          example: PayPal, Inc.
      example:
        name: John Doe
        address:
          line1: 123 Main St
          line2: Unit 201
          city: San Francisco
          state: California
          postCode: '94105'
          countryCode: 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:
                identifier:
                  type: string
                  description: The Legal Entity Identifier of the originating Virtual Asset Service Provider (VASP).
                  example: 5493001KJTIIGC8Y1R17
                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'
            personalId:
              type: string
              description: 'Personal identifier for travel rule compliance. For individuals: passport number, national ID, or driver''s license. For institutions: LEI (Legal Entity Identifier).'
              example: 123-45-6789
            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:
          $ref: '#/components/schemas/IsIntermediary'
        attestVerifiedWalletOwnership:
          type: boolean
          description: |-
            When `true`, you attest that the beneficiary's wallet ownership has been verified out-of-band. Instructs Coinbase to skip the wallet verification check for this transfer.

            **Only valid when `isIntermediary` is `true`.** You can only attest to the beneficiary's wallet ownership when your organization is acting as the originating VASP on behalf of your end customer, and Coinbase is acting as the intermediary VASP. Returns a `400` error if set to `true` when `isIntermediary` is `false` or omitted.
          example: true
        originator:
          $ref: '#/components/schemas/TravelRuleOriginator'
        beneficiary:
          $ref: '#/components/schemas/TravelRuleBeneficiary'
      example:
        isSelf: false
        isIntermediary: true
        attestVerifiedWalletOwnership: 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.
          virtualAssetServiceProvider:
            identifier: 5493001KJTIIGC8Y1R17
            name: Fidelity Digital Asset Services, LLC
            address:
              line1: 123 Market St
              line2: Suite 400
              city: San Francisco
              state: California
              postCode: '94105'
              countryCode: US
          personalId: 123-45-6789
          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:
          allOf:
            - $ref: '#/components/schemas/PositiveDecimal'
          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:
          allOf:
            - $ref: '#/components/schemas/TravelRule'
          description: Travel Rule compliance information for this transfer. Required for transfers to external wallets above regulatory thresholds. Fields required differ by region and Coinbase contracting entity.
          example:
            isSelf: false
            isIntermediary: false
            originator:
              name: John Doe
              address:
                line1: 123 Main St
                city: San Francisco
                state: CA
                postCode: '94105'
                countryCode: US
            beneficiary:
              name: Jane Smith
              walletType: custodial
      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'
        financialInstitution:
          type: string
          description: Name of the financial institution.
          example: PayPal, Inc.
        virtualAssetServiceProvider:
          $ref: '#/components/schemas/DepositTravelRuleVasp'
        personalId:
          type: string
          description: 'Personal identifier for travel rule compliance. For individuals: passport number, national ID, or driver''s license. For institutions: LEI (Legal Entity Identifier).'
          example: 123-45-6789
        dateOfBirth:
          allOf:
            - $ref: '#/components/schemas/DateOfBirth'
          description: Date of birth of the originator.
        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
      example:
        name: John Doe
        address:
          line1: 123 Main St
          city: San Francisco
          state: CA
          postCode: '94105'
          countryCode: US
        financialInstitution: PayPal, Inc.
        virtualAssetServiceProvider:
          identifier: 5493001KJTIIGC8Y1R17
          name: Fidelity Digital Asset Services, LLC
        personalId: 123-45-6789
        dateOfBirth:
          day: '15'
          month: '08'
          year: '1990'
        walletType: custodial
    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:
        isSelf:
          type: boolean
          description: Indicates whether the user attests that the originating wallet belongs to them.
          example: false
        isIntermediary:
          $ref: '#/components/schemas/IsIntermediary'
        attestVerifiedWalletOwnership:
          type: boolean
          description: |-
            When `true`, you attest that the originating wallet's ownership has been verified out-of-band. Instructs Coinbase to skip the wallet verification check for this travel-rule submission.

            **Only valid when `isIntermediary` is `true`.** You can only attest to the originating wallet's ownership when your organization is acting as the originating VASP on behalf of your end customer, and Coinbase is acting as the intermediary VASP. Returns a `400` error if set to `true` when `isIntermediary` is `false` or omitted.
          example: true
        originator:
          allOf:
            - $ref: '#/components/schemas/DepositTravelRuleOriginator'
          description: Originator information for the travel rule submission.
        beneficiary:
          allOf:
            - $ref: '#/components/schemas/DepositTravelRuleBeneficiary'
          description: Beneficiary information for the travel rule submission.
      example:
        isSelf: false
        isIntermediary: true
        attestVerifiedWalletOwnership: true
        originator:
          name: John Doe
          address:
            line1: 123 Main St
            city: San Francisco
            state: CA
            postCode: '94105'
            countryCode: US
          financialInstitution: PayPal, Inc.
          virtualAssetServiceProvider:
            identifier: 5493001KJTIIGC8Y1R17
            name: Fidelity Digital Asset Services, LLC
          personalId: 123-45-6789
          dateOfBirth:
            day: '15'
            month: '08'
            year: '1990'
          walletType: custodial
        beneficiary:
          name: Jane Smith
    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
      x-enum-varnames:
        - PaymentSessionStatusCreated
        - PaymentSessionStatusCanceled
        - PaymentSessionStatusAuthorizationPending
        - PaymentSessionStatusAuthorizationSucceeded
        - PaymentSessionStatusAuthorizationFailed
        - PaymentSessionStatusCapturePending
        - PaymentSessionStatusCaptureSucceeded
        - PaymentSessionStatusCaptureFailed
        - PaymentSessionStatusVoidPending
        - PaymentSessionStatusVoidSucceeded
        - PaymentSessionStatusVoidFailed
        - PaymentSessionStatusRefundPending
        - PaymentSessionStatusRefundSucceeded
        - PaymentSessionStatusRefundFailed
      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://payments.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: A merchant-provided internal identifier for this payment session, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.
          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://payments.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
          displayAmount:
            amount: '1.37'
            currency: 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'
    Person:
      type: object
      description: A natural person, identified by name and physical address.
      properties:
        name:
          type: string
          description: Full legal name of the person.
          example: John Doe
        address:
          allOf:
            - $ref: '#/components/schemas/PhysicalAddress'
          description: Physical address of the person.
      example:
        name: John Doe
        address:
          line1: 123 Market St
          city: San Francisco
          state: CA
          postCode: '94105'
          countryCode: US
    PaymentSessionCompliance:
      type: object
      description: |-
        Compliance context for a payment session request. Extends the base Compliance schema with buyer information required for travel rule obligations.
        This object is request-only — it is never echoed back in responses.
      allOf:
        - $ref: '#/components/schemas/Compliance'
        - type: object
          properties:
            buyer:
              allOf:
                - $ref: '#/components/schemas/Person'
              writeOnly: true
              description: Information about the person paying. Required by some entity configurations to meet regulatory requirements for fund transfers. When required, omitting this field or leaving required sub-fields empty returns a 400 listing the specific fields needed.
      example:
        buyer:
          name: John Doe
          address:
            line1: 123 Market St
            city: San Francisco
            state: CA
            postCode: '94105'
            countryCode: US
    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: A merchant-provided internal identifier for this payment session, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.
          example: merchant-order-abc123
        customerDisplay:
          $ref: '#/components/schemas/CustomerDisplay'
        metadata:
          $ref: '#/components/schemas/Metadata'
        compliance:
          allOf:
            - $ref: '#/components/schemas/PaymentSessionCompliance'
          writeOnly: true
          description: Compliance context for this payment session. Carries buyer information required by some entity configurations to meet regulatory requirements.
          example:
            buyer:
              name: John Doe
              address:
                line1: 123 Market St
                city: San Francisco
                state: CA
                postCode: '94105'
                countryCode: US
      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'
    WalletAuthorizationFundsRequirement:
      type: object
      title: Wallet Authorization Funds Requirement
      description: Describes, for one enabled (network, asset) combination, what the payer would need to fund a source address with so that it becomes eligible to authorize the payment. Appears in the `fundsRequired` list of an ineligible address whose `code` is `insufficient_funds`. All amounts are human-readable decimal strings, formatted the same way as `WalletAuthorizationOption.amount`.
      properties:
        asset:
          allOf:
            - $ref: '#/components/schemas/Asset'
          description: The symbol of the asset the payer would fund on this network.
          example: usdc
        network:
          allOf:
            - $ref: '#/components/schemas/PaymentSourceNetwork'
          description: The blockchain network this funding requirement applies to.
          example: base
        currentBalance:
          type: string
          description: A decimal representation of the address's current balance of `asset` on this `network`.
          example: '0.40'
        requiredBalance:
          type: string
          description: A decimal representation of the balance of `asset` the payer must hold on this `network` to become eligible to authorize the payment.
          example: '1.00'
      required:
        - asset
        - network
        - currentBalance
        - requiredBalance
      example:
        asset: usdc
        network: base
        currentBalance: '0.40'
        requiredBalance: '1.00'
    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
            - superseded_by_preferred_option
          x-enum-descriptions:
            - The address does not hold enough of the session asset on a supported source network to cover the session amount.
            - The address was superseded because a preferred funding option was selected instead.
          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.
        fundsRequired:
          type: array
          description: The funding options for this address, one entry per (network, asset) combination the payer could fund to become eligible. Only present when `code` is `insufficient_funds`, and honors the request's `network` and `asset` filters. May be an empty array.
          items:
            $ref: '#/components/schemas/WalletAuthorizationFundsRequirement'
          example:
            - asset: usdc
              network: base
              currentBalance: '0.40'
              requiredBalance: '1.00'
            - asset: usdc
              network: ethereum
              currentBalance: '0.00'
              requiredBalance: '1.00'
      required:
        - address
        - code
        - message
      example:
        address: '0xDeF9876543210FeDcBa9876543210FedcBa987654'
        code: insufficient_funds
        message: The payer does not have sufficient funds.
        fundsRequired:
          - asset: usdc
            network: base
            currentBalance: '0.40'
            requiredBalance: '1.00'
          - asset: usdc
            network: ethereum
            currentBalance: '0.00'
            requiredBalance: '1.00'
    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'
        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
      example:
        amount: '1.00'
        finalCapture: true
    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
      example:
        source:
          accountId: account_af2937b0-9846-4fe7-bfe9-ccc22d935114
          asset: usdc
        amount: '0.50'
        reason: Customer returned the item.
    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
    Network:
      type: string
      description: The blockchain network for the payment. Supported networks depend on the account type.
      enum:
        - base
        - ethereum
        - solana
        - aptos
        - arbitrum
        - arbitrum-sepolia
        - optimism
        - polygon
        - world
        - world-sepolia
      example: base
    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 disbursed 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: A merchant-provided internal identifier for this disbursement, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.
          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'
    DisbursementCompliance:
      type: object
      description: |-
        Compliance context for a disbursement request. Extends the base Compliance schema with recipient information required for travel rule obligations.
        This object is request-only — it is never echoed back in responses.
      allOf:
        - $ref: '#/components/schemas/Compliance'
        - type: object
          properties:
            recipient:
              allOf:
                - $ref: '#/components/schemas/Person'
              writeOnly: true
              description: Information about the person receiving this disbursement. Required by some entity configurations to meet regulatory requirements for fund transfers. When required, omitting this field or leaving required sub-fields empty returns a 400 listing the specific fields needed.
      example:
        recipient:
          name: Jane Smith
          address:
            line1: 456 Oak Ave
            city: Austin
            state: TX
            postCode: '78701'
            countryCode: US
    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 disburse, 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: A merchant-provided internal identifier for this disbursement, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.
          example: disbursement-2026-04-1234
        metadata:
          $ref: '#/components/schemas/Metadata'
        compliance:
          allOf:
            - $ref: '#/components/schemas/DisbursementCompliance'
          writeOnly: true
          description: Compliance context for this disbursement. Carries recipient information required by some entity configurations to meet regulatory requirements.
      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
        compliance:
          recipient:
            name: Jane Smith
            address:
              line1: 456 Oak Ave
              city: Austin
              state: TX
              postCode: '78701'
              countryCode: US
        metadata:
          customer_id: cust_12345
          order_id: order_67890
    EmailAuthentication:
      type: object
      title: EmailAuthentication
      description: Information about an end user who authenticates using a one-time password sent to their email address.
      properties:
        type:
          type: string
          description: The type of authentication information.
          example: email
          enum:
            - email
        email:
          allOf:
            - $ref: '#/components/schemas/Email'
          description: The email address of the end user.
          example: user@example.com
      required:
        - type
        - email
    SmsAuthentication:
      type: object
      title: SmsAuthentication
      description: Information about an end user who authenticates using a one-time password sent to their phone number via SMS.
      properties:
        type:
          type: string
          description: The type of authentication information.
          example: sms
          enum:
            - sms
        phoneNumber:
          allOf:
            - $ref: '#/components/schemas/PhoneNumber'
          description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
          example: '+12055555555'
      required:
        - type
        - phoneNumber
    DeveloperJWTAuthentication:
      type: object
      title: DeveloperJWTAuthentication
      description: Information about an end user who authenticates using a JWT issued by the developer.
      properties:
        type:
          type: string
          description: The type of authentication information.
          enum:
            - jwt
          example: jwt
        kid:
          type: string
          description: The key ID of the JWK used to sign the JWT.
          example: NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg
        sub:
          type: string
          description: The unique identifier for the end user that is captured in the `sub` claim of the JWT.
          example: e051beeb-7163-4527-a5b6-35e301529ff2
      required:
        - type
        - sub
        - kid
    OAuth2ProviderType:
      type: string
      description: The type of OAuth2 provider.
      enum:
        - google
        - apple
        - x
        - telegram
        - github
      example: google
    OAuth2Authentication:
      type: object
      title: OAuth2Authentication
      description: Information about an end user who authenticates using a third-party provider.
      properties:
        type:
          $ref: '#/components/schemas/OAuth2ProviderType'
        sub:
          type: string
          description: The unique identifier for the end user that is captured in the `sub` claim of the JWT.
          example: e051beeb-7163-4527-a5b6-35e301529ff2
        email:
          type: string
          description: The email address of the end user contained within the user's ID token, if available from third-party OAuth2 provider's token exchange.
          example: test.user@gmail.com
        name:
          type: string
          description: The full name of the end user if available from third-party OAuth2 provider's token exchange.
          example: Test User
        username:
          type: string
          description: The username of the end user if available from third-party OAuth2 provider's token exchange.
          example: test.user
      required:
        - type
        - sub
    TelegramAuthentication:
      type: object
      description: Information about an end user who authenticates using Telegram.
      properties:
        type:
          $ref: '#/components/schemas/OAuth2ProviderType'
        id:
          type: integer
          description: The Telegram ID for the end user.
          example: 123456
        firstName:
          type: string
          description: The Telegram user's first name.
          example: Satoshi
        lastName:
          type: string
          description: The Telegram user's last name.
          example: Nakamoto
        photoUrl:
          type: string
          description: The Telegram user's profile picture.
          example: https://image.url/profile.png
        authDate:
          type: integer
          description: The Telegram user's last login as a Unix timestamp.
          example: 1770681412
        username:
          type: string
          description: The Telegram user's username.
          example: satoshinakamoto
      required:
        - type
        - id
        - authDate
    SiweAuthentication:
      type: object
      title: SiweAuthentication
      description: Information about an end user who authenticates using Sign In With Ethereum (EIP-4361).
      properties:
        type:
          type: string
          description: The type of authentication information.
          example: siwe
          enum:
            - siwe
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: The ERC-55 checksummed Ethereum address of the end user.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      required:
        - type
        - address
    AuthenticationMethod:
      description: Information about how the end user is authenticated.
      oneOf:
        - $ref: '#/components/schemas/EmailAuthentication'
        - $ref: '#/components/schemas/SmsAuthentication'
        - $ref: '#/components/schemas/DeveloperJWTAuthentication'
        - $ref: '#/components/schemas/OAuth2Authentication'
        - $ref: '#/components/schemas/TelegramAuthentication'
        - $ref: '#/components/schemas/SiweAuthentication'
    AuthenticationMethods:
      type: array
      description: The list of valid authentication methods linked to the end user.
      items:
        $ref: '#/components/schemas/AuthenticationMethod'
      example:
        - type: email
          email: user@example.com
        - type: sms
          phoneNumber: '+12055555555'
        - type: jwt
          sub: e051beeb-7163-4527-a5b6-35e301529ff2
          kid: NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg
        - type: google
          sub: '115346410074741490243'
          email: test.user@gmail.com
        - type: telegram
          id: 1223456
          firstName: Satoshi
          lastName: Nakamoto
          photoUrl: https://image.url/profile.jpg
          authDate: 1770681412
          username: satoshinakamoto
        - type: siwe
          address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    MFAMethods:
      x-audience: public
      description: |
        Information about the end user's MFA enrollments.
      type: object
      properties:
        enrollmentPromptedAt:
          type: string
          format: date-time
          description: The date and time when the end user was prompted for MFA enrollment, in ISO 8601 format. If the this field exists, and the user has no other enrolled MFA methods, then the user skipped MFA enrollment.
          example: '2025-01-15T10:30:00Z'
        totp:
          type: object
          description: An object containing information about the end user's TOTP enrollment.
          required:
            - enrolledAt
          properties:
            enrolledAt:
              type: string
              format: date-time
              description: The date and time when the method was enrolled, in ISO 8601 format.
              example: '2025-01-15T10:30:00Z'
        sms:
          type: object
          description: An object containing information about the end user's SMS MFA enrollment.
          required:
            - enrolledAt
          properties:
            enrolledAt:
              type: string
              format: date-time
              description: The date and time when the method was enrolled, in ISO 8601 format.
              example: '2025-01-15T10:30:00Z'
      example:
        enrollmentPromptedAt: '2025-01-15T10:30:00Z'
        totp:
          enrolledAt: '2025-01-15T10:30:00Z'
        sms:
          enrolledAt: '2025-01-15T10:30:00Z'
    EndUserEvmAccount:
      type: object
      description: Information about an EVM account associated with an end user.
      properties:
        address:
          type: string
          description: The address of the EVM account.
          pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        createdAt:
          type: string
          format: date-time
          description: The date and time when the account was created, in ISO 8601 format.
          example: '2025-01-15T10:30:00Z'
        exportedAt:
          type: string
          format: date-time
          nullable: true
          description: The date and time when the account's private key was first exported, in ISO 8601 format. This is set on the first export and preserved on subsequent exports; it is not updated on re-export.
          example: null
        ejectedAt:
          type: string
          format: date-time
          nullable: true
          description: The date and time when the account's key was ejected (marked for deletion), in ISO 8601 format. Populated when the account has been ejected. The account record remains queryable after this timestamp is set; it reflects when ejection was requested, not when the key material is purged.
          example: null
      required:
        - address
        - createdAt
    EndUserEvmSmartAccount:
      type: object
      description: Information about an EVM smart account associated with an end user.
      properties:
        address:
          type: string
          description: The address of the EVM smart account.
          pattern: ^0x[0-9a-fA-F]{40}$
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        ownerAddresses:
          type: array
          description: The addresses of the EVM EOA accounts that own this smart account. Smart accounts can have multiple owners, such as when spend permissions are enabled.
          items:
            type: string
            description: The address of an EVM EOA account that owns this smart account.
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0x1234567890abcdef1234567890abcdef12345678'
          example:
            - '0x1234567890abcdef1234567890abcdef12345678'
            - '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd'
        createdAt:
          type: string
          format: date-time
          description: The date and time when the account was created, in ISO 8601 format.
          example: '2025-01-15T10:30:00Z'
      required:
        - address
        - ownerAddresses
        - createdAt
    EndUserSolanaAccount:
      type: object
      description: Information about a Solana account associated with an end user.
      properties:
        address:
          type: string
          description: The base58 encoded address of the Solana account.
          pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        createdAt:
          type: string
          format: date-time
          description: The date and time when the account was created, in ISO 8601 format.
          example: '2025-01-15T10:30:00Z'
        exportedAt:
          type: string
          format: date-time
          nullable: true
          description: The date and time when the account's private key was first exported, in ISO 8601 format. This is set on the first export and preserved on subsequent exports; it is not updated on re-export.
          example: null
        ejectedAt:
          type: string
          format: date-time
          nullable: true
          description: The date and time when the account's key was ejected (marked for deletion), in ISO 8601 format. Populated when the account has been ejected. The account record remains queryable after this timestamp is set; it reflects when ejection was requested, not when the key material is purged.
          example: null
      required:
        - address
        - createdAt
    EndUser:
      type: object
      description: Information about the end user.
      properties:
        userId:
          description: A stable, unique identifier for the end user. The `userId` must be unique across all end users in the developer's CDP Project. It must be between 1 and 100 characters long and can only contain alphanumeric characters and hyphens.
          type: string
          pattern: ^[a-zA-Z0-9-]{1,100}$
          example: e051beeb-7163-4527-a5b6-35e301529ff2
        authenticationMethods:
          $ref: '#/components/schemas/AuthenticationMethods'
        mfaMethods:
          $ref: '#/components/schemas/MFAMethods'
        evmAccounts:
          type: array
          deprecated: true
          description: '**DEPRECATED**: Use `evmAccountObjects` instead for richer account information. The list of EVM account addresses associated with the end user. End users can have up to 10 EVM accounts.'
          items:
            type: string
            description: The address of the EVM account associated with the end user.
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          example:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        evmAccountObjects:
          type: array
          description: The list of EVM accounts associated with the end user. End users can have up to 10 EVM accounts.
          items:
            $ref: '#/components/schemas/EndUserEvmAccount'
          example:
            - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              createdAt: '2025-01-15T10:30:00Z'
            - address: '0x1234567890abcdef1234567890abcdef12345678'
              createdAt: '2025-01-15T11:00:00Z'
        evmSmartAccounts:
          type: array
          deprecated: true
          description: '**DEPRECATED**: Use `evmSmartAccountObjects` instead for richer account information including owner relationships. The list of EVM smart account addresses associated with the end user. Each EVM EOA can own one smart account.'
          items:
            type: string
            description: The address of the EVM smart account associated with the end user.
            pattern: ^0x[0-9a-fA-F]{40}$
            example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          example:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        evmSmartAccountObjects:
          type: array
          description: The list of EVM smart accounts associated with the end user. Each EVM EOA can own one smart account.
          items:
            $ref: '#/components/schemas/EndUserEvmSmartAccount'
          example:
            - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              ownerAddresses:
                - '0x1234567890abcdef1234567890abcdef12345678'
                - '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd'
              createdAt: '2025-01-15T12:00:00Z'
        solanaAccounts:
          type: array
          deprecated: true
          description: '**DEPRECATED**: Use `solanaAccountObjects` instead for richer account information. The list of Solana account addresses associated with the end user. End users can have up to 10 Solana accounts.'
          items:
            type: string
            description: The base58 encoded address of the Solana account associated with the end user.
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
            example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          example:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        solanaAccountObjects:
          type: array
          description: The list of Solana accounts associated with the end user. End users can have up to 10 Solana accounts.
          items:
            $ref: '#/components/schemas/EndUserSolanaAccount'
          example:
            - address: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
              createdAt: '2025-01-15T10:30:00Z'
            - address: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
              createdAt: '2025-01-15T11:30:00Z'
        createdAt:
          type: string
          format: date-time
          description: The date and time when the end user was created, in ISO 8601 format.
          example: '2025-01-15T10:30:00Z'
      required:
        - userId
        - authenticationMethods
        - evmAccounts
        - evmAccountObjects
        - evmSmartAccounts
        - evmSmartAccountObjects
        - solanaAccounts
        - solanaAccountObjects
        - createdAt
    PaymasterContext:
      type: object
      additionalProperties: true
      description: The ERC-7677 `context` object forwarded to the paymaster service as part of the `paymasterService` capability. The fields in this object are defined by the paymaster service provider; CDP forwards them to the paymaster unchanged. This field is only valid when a paymaster is configured for the request. Providing `paymasterContext` without a paymaster configured results in an `invalid_request` error.
      example:
        policyId: 962b252c-a726-4a37-8d86-333ce0a07299
    EvmEip7702DelegationNetwork:
      type: string
      description: The network for the EIP-7702 delegation.
      enum:
        - base-sepolia
        - base
        - arbitrum
        - optimism
        - polygon
        - ethereum
        - ethereum-sepolia
      example: base
    EvmUserOperationNetwork:
      type: string
      description: The network the user operation is for.
      enum:
        - base-sepolia
        - base
        - arbitrum
        - optimism
        - zora
        - polygon
        - bnb
        - avalanche
        - ethereum
        - ethereum-sepolia
      example: base
    EvmCall:
      type: object
      properties:
        to:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The address the call is directed to.
          example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        value:
          type: string
          description: The amount of ETH to send with the call, in wei.
          example: '0'
        data:
          type: string
          pattern: ^0x[0-9a-fA-F]*$
          description: The call data to send. This is the hex-encoded data of the function call consisting of the method selector and the function arguments.
          example: '0xa9059cbb000000000000000000000000fc807d1be4997e5c7b33e4d8d57e60c5b0f02b1a0000000000000000000000000000000000000000000000000000000000000064'
        overrideGasLimit:
          type: string
          description: The override gas limit to use for the call instead of the bundler's estimated gas limit.
          example: '100000'
      required:
        - to
        - value
        - data
    UserOperationReceiptRevert:
      type: object
      description: The revert data if the user operation has reverted.
      properties:
        data:
          type: string
          pattern: ^0x[0-9a-fA-F]*$
          description: The 0x-prefixed raw hex string.
          example: '0x123'
        message:
          type: string
          description: Human-readable revert reason if able to decode.
          example: reason for failure
      required:
        - data
        - message
      example:
        data: '0x123'
        message: reason for failure
    UserOperationReceipt:
      type: object
      description: The receipt that contains information about the execution of user operation.
      properties:
        revert:
          $ref: '#/components/schemas/UserOperationReceiptRevert'
        transactionHash:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
          description: The hash of this transaction as 0x-prefixed string.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        blockHash:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$|^$
          description: The block hash of the block including the transaction as 0x-prefixed string.
          example: '0x386544b58930c0ec9e8f3ed09fb4cdb76b9ae0a1a37ddcacebe3925b57978e65'
        blockNumber:
          type: integer
          description: The block height (number) of the block including the transaction.
          example: 29338819
        gasUsed:
          type: string
          description: The gas used for landing this user operation.
          example: '100000'
      example:
        revert:
          data: '0x123'
          message: reason for failure
        blockHash: '0x386544b58930c0ec9e8f3ed09fb4cdb76b9ae0a1a37ddcacebe3925b57978e65'
        blockNumber: 29338819
        gasUsed: '100000'
    EvmUserOperation:
      type: object
      properties:
        network:
          $ref: '#/components/schemas/EvmUserOperationNetwork'
        userOpHash:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
          description: The hash of the user operation. This is not the transaction hash, as a transaction consists of multiple user operations. The user operation hash is the hash of this particular user operation which gets signed by the owner of the Smart Account.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        calls:
          type: array
          description: The list of calls in the user operation.
          items:
            $ref: '#/components/schemas/EvmCall'
          example:
            - to: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
              value: '0'
              data: '0xa9059cbb000000000000000000000000fc807d1be4997e5c7b33e4d8d57e60c5b0f02b1a0000000000000000000000000000000000000000000000000000000000000064'
            - to: '0xdac17f958d2ee523a2206206994597c13d831ec7'
              value: '1000000000000000'
              data: 0x
        status:
          type: string
          description: The status of the user operation.
          enum:
            - pending
            - signed
            - broadcast
            - complete
            - dropped
            - failed
          example: pending
        transactionHash:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$|^$
          description: The hash of the transaction that included this particular user operation. This gets set after the user operation is broadcasted and the transaction is included in a block.
          example: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
        receipts:
          type: array
          description: The list of receipts associated with the user operation.
          items:
            $ref: '#/components/schemas/UserOperationReceipt'
          example:
            - revert:
                data: '0x123'
                message: reason for failure
              blockHash: '0x386544b58930c0ec9e8f3ed09fb4cdb76b9ae0a1a37ddcacebe3925b57978e65'
              blockNumber: 29338819
              gasUsed: '100000'
        expiresAt:
          type: string
          description: The timestamp at which the prepared user operation expires.
          example: '2025-03-25T12:00:00Z'
          format: date-time
      required:
        - network
        - userOpHash
        - calls
        - status
    X402Version:
      type: integer
      description: The version of the x402 protocol.
      enum:
        - 1
        - 2
      example: 2
    X402V2Network:
      type: string
      description: 'The x402 v2 network identifier in CAIP-2 format. x402 v2 identifies networks by their CAIP-2 chain ID (e.g. `eip155:<chainId>` for EVM networks, `solana:<genesisHash>` for Solana). Supported networks: Base, Polygon, Arbitrum One, World Chain (EVM), and Solana.'
      enum:
        - eip155:8453
        - eip155:84532
        - eip155:137
        - eip155:42161
        - eip155:480
        - eip155:4801
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        - solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
      example: eip155:8453
    x402V2PaymentRequirements:
      type: object
      title: x402V2PaymentRequirements
      description: The x402 v2 payment requirements. Uses CAIP-2 network identifiers and supports `exact`, `upto`, and `batch-settlement` schemes. Carries only the payment fields (no resource metadata — that is in the enclosing `x402V2PaymentPayload.resource`).
      properties:
        scheme:
          type: string
          description: The scheme of the payment protocol to use. Supported schemes are `exact`, `upto`, and `batch-settlement`.
          enum:
            - exact
            - upto
            - batch-settlement
          example: exact
        network:
          allOf:
            - $ref: '#/components/schemas/X402V2Network'
          description: The network of the blockchain to send payment on in CAIP-2 format.
          example: eip155:8453
        asset:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: |-
            The asset to pay with.

            For EVM networks, the asset will be a 0x-prefixed, checksum EVM address.

            For Solana-based networks, the asset will be a base58-encoded Solana address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        amount:
          type: string
          description: The amount to pay for the resource in atomic units of the payment asset.
          example: '1000000'
        payTo:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: |-
            The destination to pay value to.

            For EVM networks, payTo will be a 0x-prefixed, checksum EVM address.

            For Solana-based networks, payTo will be a base58-encoded Solana address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        maxTimeoutSeconds:
          type: integer
          description: The maximum time in seconds for the resource server to respond.
          example: 10
        extra:
          type: object
          description: The optional additional scheme-specific payment info.
          additionalProperties: true
          example:
            name: USDC
            version: '2'
      required:
        - scheme
        - network
        - asset
        - amount
        - payTo
        - maxTimeoutSeconds
    X402V1Network:
      type: string
      description: 'The x402 v1 network identifier. x402 v1 uses human-readable network names. Supported networks: Base mainnet and testnet, Solana mainnet and devnet.'
      enum:
        - base
        - base-sepolia
        - solana
        - solana-devnet
      example: base
    Description:
      type: string
      minLength: 0
      maxLength: 500
      description: A human-readable description.
      example: A description of the resource.
    x402V1PaymentRequirements:
      type: object
      title: x402V1PaymentRequirements
      description: The x402 v1 payment requirements. Uses human-readable network names, and carries resource metadata (`resource`, `description`, `mimeType`) alongside the payment fields. The only supported scheme is `exact`.
      properties:
        scheme:
          type: string
          description: The scheme of the payment protocol to use. Currently, the only supported scheme is `exact`.
          enum:
            - exact
          example: exact
        network:
          allOf:
            - $ref: '#/components/schemas/X402V1Network'
          description: The network of the blockchain to send payment on.
          example: base
        maxAmountRequired:
          type: string
          description: The maximum amount required to pay for the resource in atomic units of the payment asset.
          example: '1000000'
        resource:
          type: string
          description: The URL of the resource to pay for.
          example: https://api.example.com/premium/resource/123
        description:
          allOf:
            - $ref: '#/components/schemas/Description'
          description: A human-readable description of the resource.
          example: Premium API access for data analysis
        mimeType:
          type: string
          description: The MIME type of the resource response.
          example: application/json
        outputSchema:
          type: object
          description: The optional JSON schema describing the resource output.
          additionalProperties: true
          example:
            data: string
        payTo:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: |-
            The destination to pay value to.

            For EVM networks, payTo will be a 0x-prefixed, checksum EVM address.

            For Solana-based networks, payTo will be a base58-encoded Solana address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        maxTimeoutSeconds:
          type: integer
          description: The maximum time in seconds for the resource server to respond.
          example: 10
        asset:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: |-
            The asset to pay with.

            For EVM networks, the asset will be a 0x-prefixed, checksum EVM address.

            For Solana-based networks, the asset will be a base58-encoded Solana address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        extra:
          type: object
          description: The optional additional scheme-specific payment info.
          additionalProperties: true
          example:
            gasLimit: '1000000'
      required:
        - scheme
        - network
        - maxAmountRequired
        - resource
        - description
        - mimeType
        - payTo
        - asset
        - maxTimeoutSeconds
    x402PaymentRequirements:
      type: object
      description: The x402 protocol payment requirements that the resource server expects the client's payment payload to meet.
      oneOf:
        - $ref: '#/components/schemas/x402V2PaymentRequirements'
        - $ref: '#/components/schemas/x402V1PaymentRequirements'
    x402ResourceInfo:
      type: object
      description: Describes the resource being accessed in x402 protocol.
      properties:
        url:
          type: string
          description: The URL of the resource.
          example: https://api.example.com/premium/resource/123
        description:
          allOf:
            - $ref: '#/components/schemas/Description'
          description: A human-readable description of the resource.
          example: Premium API access for data analysis
        mimeType:
          type: string
          description: The MIME type of the resource response.
          example: application/json
    x402PaymentRequired:
      type: object
      description: The x402 protocol payment required response body, returned by a resource server when a request lacks valid payment. Contains the accepted payment options, optional resource metadata, and an optional error message from the resource server.
      properties:
        x402Version:
          allOf:
            - $ref: '#/components/schemas/X402Version'
          description: The x402 protocol version.
          example: 2
        accepts:
          type: array
          description: The list of payment options the resource server accepts. At least one option must be present.
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/x402PaymentRequirements'
          example:
            - scheme: exact
              network: eip155:8453
              amount: '1000000'
              asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
              payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              maxTimeoutSeconds: 60
            - scheme: exact
              network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
              amount: '1000000'
              asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
              payTo: 2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
              maxTimeoutSeconds: 60
        resource:
          allOf:
            - $ref: '#/components/schemas/x402ResourceInfo'
          description: Optional metadata about the resource being paid for.
          example:
            url: https://api.example.com/premium/resource/123
            description: Premium API access for data analysis.
            mimeType: application/json
        error:
          type: string
          description: An optional error message from the resource server describing why payment is required.
          example: PAYMENT-SIGNATURE header is required
        extensions:
          type: object
          description: Optional protocol extensions. Unknown keys are forwarded as-is into the signed payment payload.
          additionalProperties: true
          example: {}
      required:
        - x402Version
        - accepts
    x402ExactEvmPayload:
      type: object
      title: x402ExactEvmPayload
      description: The x402 protocol exact scheme payload for EVM networks. The scheme is implemented using ERC-3009. For more details, please see [EVM Exact Scheme Details](https://github.com/coinbase/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md).
      properties:
        signature:
          type: string
          pattern: ^0x[0-9a-fA-F]{130,}$
          description: The EIP-712 hex-encoded signature of the ERC-3009 authorization message. Smart account signatures may be longer than 65 bytes.
          example: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        authorization:
          type: object
          description: The authorization data for the ERC-3009 authorization message.
          properties:
            from:
              type: string
              pattern: ^0x[0-9a-fA-F]{40}$
              description: The 0x-prefixed, checksum EVM address of the sender of the payment.
              example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            to:
              type: string
              pattern: ^0x[0-9a-fA-F]{40}$
              description: The 0x-prefixed, checksum EVM address of the recipient of the payment.
              example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            value:
              type: string
              description: The value of the payment, in atomic units of the payment asset.
              example: '1000000000000000000'
            validAfter:
              type: string
              description: The unix timestamp after which the payment is valid.
              example: '1716150000'
            validBefore:
              type: string
              description: The unix timestamp before which the payment is valid.
              example: '1716150000'
            nonce:
              type: string
              pattern: ^0x[0-9a-fA-F]{64}$
              description: The hex-encoded nonce of the payment (bytes32).
              example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
          example:
            from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            value: '1000000000000000000'
            validAfter: '1716150000'
            validBefore: '1716150000'
            nonce: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
          required:
            - from
            - to
            - value
            - validAfter
            - validBefore
            - nonce
      example:
        signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        authorization:
          from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          value: '1000000000000000000'
          validAfter: '1716150000'
          validBefore: '1716150000'
          nonce: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
      required:
        - signature
        - authorization
    x402ExactEvmPermit2Payload:
      type: object
      title: x402ExactEvmPermit2Payload
      description: The x402 protocol exact scheme payload for EVM networks using Permit2. Permit2 is a universal token approval mechanism that works with any ERC-20 token, unlike ERC-3009 which requires token-level support.
      properties:
        signature:
          type: string
          pattern: ^0x[0-9a-fA-F]{130,}$
          description: The EIP-712 hex-encoded signature of the Permit2 PermitWitnessTransferFrom message. Smart account signatures may be longer than 65 bytes.
          example: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        permit2Authorization:
          type: object
          description: The authorization data for the Permit2 PermitWitnessTransferFrom message.
          properties:
            from:
              type: string
              pattern: ^0x[0-9a-fA-F]{40}$
              description: The 0x-prefixed, checksum EVM address of the sender of the payment.
              example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            permitted:
              type: object
              description: The token permissions for the transfer.
              properties:
                token:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: The 0x-prefixed, checksum EVM address of the token to transfer.
                  example: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                amount:
                  type: string
                  description: The amount to transfer in atomic units.
                  example: '1000000'
              required:
                - token
                - amount
            spender:
              type: string
              pattern: ^0x[0-9a-fA-F]{40}$
              description: The 0x-prefixed, checksum EVM address of the spender (x402 Permit2 proxy contract).
              example: '0x4020615294c913F045dc10f0a5cdEbd86c280001'
            nonce:
              type: string
              pattern: ^[0-9]+$
              description: The Permit2 nonce as a decimal string (uint256).
              example: '12345678901234567890'
            deadline:
              type: string
              description: The unix timestamp before which the permit is valid.
              example: '1716150000'
            witness:
              type: object
              description: The witness data containing payment details.
              properties:
                to:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: The 0x-prefixed, checksum EVM address of the recipient.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                validAfter:
                  type: string
                  description: The unix timestamp after which the payment is valid.
                  example: '1716150000'
                extra:
                  type: string
                  pattern: ^0x[0-9a-fA-F]*$
                  description: Optional hex-encoded extra data.
                  example: 0x
              additionalProperties: false
              required:
                - to
                - validAfter
          example:
            from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            permitted:
              token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
              amount: '1000000'
            spender: '0x4020615294c913F045dc10f0a5cdEbd86c280001'
            nonce: '12345678901234567890'
            deadline: '1716150000'
            witness:
              to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              validAfter: '1716150000'
              extra: 0x
          required:
            - from
            - permitted
            - spender
            - nonce
            - deadline
            - witness
      example:
        signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        permit2Authorization:
          from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          permitted:
            token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
            amount: '1000000'
          spender: '0x4020615294c913F045dc10f0a5cdEbd86c280001'
          nonce: '12345678901234567890'
          deadline: '1716150000'
          witness:
            to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            validAfter: '1716150000'
            extra: 0x
      required:
        - signature
        - permit2Authorization
    x402ExactSolanaPayload:
      type: object
      title: x402ExactSolanaPayload
      description: The x402 protocol exact scheme payload for Solana networks. For more details, please see [Solana Exact Scheme Details](https://github.com/coinbase/x402/blob/main/specs/schemes/exact/scheme_exact_svm.md).
      properties:
        transaction:
          type: string
          description: The base64-encoded Solana transaction.
          example: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
      example:
        transaction: AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQABAQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8CBgMBAQAAAAIBAwQAAAAABgIAAAAAAAYDBQEBAAAGBAgAAAAABgUAAAAA6AMAAAAAAAAGBgUBAQEBBgcEAQAAAAYICgMBAQIDBgkCBgAAAAYKAwABAQEGCwMGAQEBBgwDAAABAQAAAAA=
      required:
        - transaction
    x402UptoEvmPermit2Payload:
      type: object
      title: x402UptoEvmPermit2Payload
      description: The x402 protocol upto scheme payload for EVM networks using Permit2. The `upto` scheme authorizes a maximum amount and lets the facilitator settle for the actual amount used. Structurally identical to `x402ExactEvmPermit2Payload` except `permit2Authorization.witness` carries an additional `facilitator` address that binds the authorization to a specific facilitator (the one announced via `extra.facilitatorAddress` in the payment requirements). For more details, see [EVM Upto Scheme Details](https://github.com/x402-foundation/x402/blob/main/specs/schemes/upto/scheme_upto_evm.md).
      properties:
        signature:
          type: string
          pattern: ^0x[0-9a-fA-F]{130,}$
          description: The EIP-712 hex-encoded signature of the Permit2 PermitWitnessTransferFrom message. Smart account signatures may be longer than 65 bytes.
          example: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        permit2Authorization:
          type: object
          description: The authorization data for the Permit2 PermitWitnessTransferFrom message. The `permitted.amount` is the maximum the client authorizes; the actual settled amount is decided by the resource server at settle time and MUST be less than or equal to it.
          properties:
            from:
              type: string
              pattern: ^0x[0-9a-fA-F]{40}$
              description: The 0x-prefixed, checksum EVM address of the sender of the payment.
              example: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
            permitted:
              type: object
              description: The token permissions for the transfer.
              properties:
                token:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: The 0x-prefixed, checksum EVM address of the token to transfer.
                  example: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                amount:
                  type: string
                  description: The maximum amount the client authorizes to transfer in atomic units.
                  example: '5000000'
              required:
                - token
                - amount
            spender:
              type: string
              pattern: ^0x[0-9a-fA-F]{40}$
              description: The 0x-prefixed, checksum EVM address of the spender (the x402 Upto Permit2 proxy contract).
              example: '0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002'
            nonce:
              type: string
              pattern: ^[0-9]+$
              description: The Permit2 nonce as a decimal string (uint256).
              example: '12345678901234567890'
            deadline:
              type: string
              description: The unix timestamp before which the permit is valid.
              example: '1740672154'
            witness:
              type: object
              description: The witness data containing payment details. Includes a `facilitator` field to bind the authorization to a specific facilitator address.
              properties:
                to:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: The 0x-prefixed, checksum EVM address of the recipient.
                  example: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
                facilitator:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
                  description: The 0x-prefixed, checksum EVM address of the facilitator authorized to settle this payment. MUST match the `facilitatorAddress` advertised in the payment requirements `extra` field.
                  example: '0x1111111111111111111111111111111111111111'
                validAfter:
                  type: string
                  description: The unix timestamp after which the payment is valid.
                  example: '1740672089'
              required:
                - to
                - facilitator
                - validAfter
          required:
            - from
            - permitted
            - spender
            - nonce
            - deadline
            - witness
      example:
        signature: '0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c34008c8e8986a1283259764173608a2ce6496642e377d6da8dbbf5836e9bd15092f9ecab05ded3d6293af148b571c'
        permit2Authorization:
          from: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          permitted:
            token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
            amount: '5000000'
          spender: '0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002'
          nonce: '12345678901234567890'
          deadline: '1740672154'
          witness:
            to: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
            facilitator: '0x1111111111111111111111111111111111111111'
            validAfter: '1740672089'
      required:
        - signature
        - permit2Authorization
    x402BatchSettlementChannelConfig:
      type: object
      title: x402BatchSettlementChannelConfig
      description: Immutable configuration for an x402 batch-settlement payment channel. The EIP-712 hash of this struct produces the `channelId` used by all batch-settlement payloads.
      properties:
        payer:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address of the payer (channel funder).
          example: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
        payerAuthorizer:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address authorized to sign vouchers on behalf of the payer.
          example: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
        receiver:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address of the receiver (resource server / merchant).
          example: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
        receiverAuthorizer:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address authorized to sign claim batches on behalf of the receiver (typically the facilitator).
          example: '0x1111111111111111111111111111111111111111'
        token:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address of the ERC-20 payment token.
          example: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
        withdrawDelay:
          type: integer
          description: The non-cooperative withdraw delay in seconds. Must be between 900 (15 minutes) and 2,592,000 (30 days).
          minimum: 900
          maximum: 2592000
          example: 86400
        salt:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
          description: A 32-byte salt used to differentiate channels between the same payer/receiver pair.
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
      required:
        - payer
        - payerAuthorizer
        - receiver
        - receiverAuthorizer
        - token
        - withdrawDelay
        - salt
      example:
        payer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
        payerAuthorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
        receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
        receiverAuthorizer: '0x1111111111111111111111111111111111111111'
        token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
        withdrawDelay: 86400
        salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
    x402BatchSettlementVoucher:
      type: object
      title: x402BatchSettlementVoucher
      description: A signed cumulative-ceiling voucher for an x402 batch-settlement channel. `maxClaimableAmount` is monotonically increasing across requests in the same channel; the receiver may claim any amount up to this ceiling.
      properties:
        channelId:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
          description: The 32-byte EIP-712 hash of the `channelConfig` for this voucher's channel.
          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
        maxClaimableAmount:
          type: string
          pattern: ^[0-9]+$
          description: The cumulative maximum amount (uint128 as decimal string) the receiver is authorized to claim from this channel as of this voucher.
          example: '5000000'
        signature:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          description: The EIP-712 hex-encoded signature of the voucher by `payerAuthorizer`.
          example: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
      required:
        - channelId
        - maxClaimableAmount
        - signature
      example:
        channelId: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
        maxClaimableAmount: '5000000'
        signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
    x402BatchSettlementDepositPayload:
      type: object
      title: x402BatchSettlementDepositPayload
      description: Sent on the first request to fund a channel via an ERC-3009 receiveWithAuthorization deposit.
      properties:
        type:
          type: string
          description: The payload-type discriminator. Must be `"deposit"` for a channel-funding deposit payload.
          enum:
            - deposit
        channelConfig:
          $ref: '#/components/schemas/x402BatchSettlementChannelConfig'
        voucher:
          $ref: '#/components/schemas/x402BatchSettlementVoucher'
        deposit:
          type: object
          description: The deposit amount and asset-transfer authorization that funds the channel.
          properties:
            amount:
              type: string
              pattern: ^[0-9]+$
              description: The deposit amount in atomic units of `channelConfig.token`.
              example: '10000000'
            authorization:
              type: object
              description: The asset-transfer authorization for the deposit. Currently only ERC-3009 is supported.
              properties:
                erc3009Authorization:
                  type: object
                  description: An ERC-3009 receiveWithAuthorization message authorizing the channel-funding transfer.
                  properties:
                    validAfter:
                      type: string
                      description: The unix timestamp after which the authorization is valid.
                      example: '1716150000'
                    validBefore:
                      type: string
                      description: The unix timestamp before which the authorization is valid.
                      example: '1716160000'
                    salt:
                      type: string
                      pattern: ^0x[0-9a-fA-F]{64}$
                      description: The 32-byte ERC-3009 nonce/salt for replay protection.
                      example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                    signature:
                      type: string
                      pattern: ^0x[0-9a-fA-F]+$
                      description: The EIP-712 hex-encoded signature of the ERC-3009 authorization.
                      example: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
                  required:
                    - validAfter
                    - validBefore
                    - salt
                    - signature
          required:
            - amount
            - authorization
      required:
        - type
        - channelConfig
        - voucher
        - deposit
      example:
        type: deposit
        channelConfig:
          payer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          payerAuthorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
          receiverAuthorizer: '0x1111111111111111111111111111111111111111'
          token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
          withdrawDelay: 86400
          salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
        voucher:
          channelId: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
          maxClaimableAmount: '5000000'
          signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        deposit:
          amount: '10000000'
          authorization:
            erc3009Authorization:
              validAfter: '1716150000'
              validBefore: '1716160000'
              salt: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
              signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
    x402BatchSettlementVoucherPayload:
      type: object
      title: x402BatchSettlementVoucherPayload
      description: Sent on subsequent requests against an already-funded channel; carries only the latest cumulative voucher.
      properties:
        type:
          type: string
          description: The payload-type discriminator. Must be `"voucher"` for a voucher-only payment against an already-funded channel.
          enum:
            - voucher
        channelConfig:
          $ref: '#/components/schemas/x402BatchSettlementChannelConfig'
        voucher:
          $ref: '#/components/schemas/x402BatchSettlementVoucher'
      required:
        - type
        - channelConfig
        - voucher
      example:
        type: voucher
        channelConfig:
          payer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          payerAuthorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
          receiverAuthorizer: '0x1111111111111111111111111111111111111111'
          token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
          withdrawDelay: 86400
          salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
        voucher:
          channelId: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
          maxClaimableAmount: '5000000'
          signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
    x402BatchSettlementClaim:
      type: object
      title: x402BatchSettlementClaim
      description: |-
        A single voucher claim within a batched on-chain claim transaction. Used by `x402BatchSettlementClaimPayload.claims` and by the server-enriched shape of `x402BatchSettlementRefundPayload.claims`.
        NOTE: the nested `voucher` here has a **different shape** from the top-level `x402BatchSettlementVoucher` schema. The top-level voucher is the signed cumulative-ceiling message sent by a client (`{channelId, maxClaimableAmount, signature}`). This nested `voucher` mirrors the on-chain claim struct (`{channel: ChannelConfig, maxClaimableAmount}`) that participates in the EIP-712 hash, with `signature` and `totalClaimed` as siblings rather than nested fields. The field names match the upstream x402 protocol and the on-chain Solidity struct; they cannot be renamed without breaking wire and EIP-712 compatibility.
      properties:
        voucher:
          type: object
          description: The voucher to claim, identified by the channel config it was signed against and its cumulative ceiling. Field shape mirrors the on-chain claim struct.
          properties:
            channel:
              $ref: '#/components/schemas/x402BatchSettlementChannelConfig'
            maxClaimableAmount:
              type: string
              pattern: ^[0-9]+$
              description: The cumulative maximum claimable amount (uint128 as decimal string) signed by the payer authorizer.
              example: '5000000'
          required:
            - channel
            - maxClaimableAmount
        signature:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          description: The voucher signature from `payerAuthorizer`.
        totalClaimed:
          type: string
          pattern: ^[0-9]+$
          description: The cumulative amount already claimed from this channel as of this claim.
          example: '3000000'
      required:
        - voucher
        - signature
        - totalClaimed
      example:
        voucher:
          channel:
            payer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
            payerAuthorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
            receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
            receiverAuthorizer: '0x1111111111111111111111111111111111111111'
            token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
            withdrawDelay: 86400
            salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
          maxClaimableAmount: '5000000'
        signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        totalClaimed: '3000000'
    x402BatchSettlementRefundPayload:
      type: object
      title: x402BatchSettlementRefundPayload
      description: A cooperative refund request. The client emits the minimal shape (just `channelConfig` and `voucher`, with an optional `amount`). A mediating server enriches the payload with `amount`, `refundNonce`, and `claims` before forwarding to the facilitator. Authorizer signatures are optional — the facilitator auto-signs when absent. Field presence determines which shape was sent; the facilitator dispatches accordingly.
      properties:
        type:
          type: string
          description: The payload-type discriminator. Must be `"refund"` for both the client-emitted and server-enriched shape.
          enum:
            - refund
        channelConfig:
          $ref: '#/components/schemas/x402BatchSettlementChannelConfig'
        voucher:
          $ref: '#/components/schemas/x402BatchSettlementVoucher'
        amount:
          type: string
          pattern: ^[0-9]+$
          description: The refund amount in atomic units of `channelConfig.token`. Optional in the client-emitted shape (defaults to the full remaining channel balance). Required when the payload is enriched by a mediating server.
          example: '1000000'
        refundNonce:
          type: string
          pattern: ^[0-9]+$
          description: The on-chain refund nonce for replay protection (uint256 as decimal string). Only present on the server-enriched shape.
          example: '1'
        claims:
          type: array
          description: Voucher claims to include atomically with the refund. Only present on the server-enriched shape.
          items:
            $ref: '#/components/schemas/x402BatchSettlementClaim'
        refundAuthorizerSignature:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          description: Optional EIP-712 signature from the receiver authorizer over the refund. When omitted, the facilitator auto-signs.
        claimAuthorizerSignature:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          description: Optional EIP-712 signature from the receiver authorizer over the included claims. When omitted, the facilitator auto-signs.
      required:
        - type
        - channelConfig
        - voucher
      example:
        type: refund
        channelConfig:
          payer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          payerAuthorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
          receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
          receiverAuthorizer: '0x1111111111111111111111111111111111111111'
          token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
          withdrawDelay: 86400
          salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
        voucher:
          channelId: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
          maxClaimableAmount: '5000000'
          signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
        amount: '1000000'
    x402BatchSettlementClaimPayload:
      type: object
      title: x402BatchSettlementClaimPayload
      description: Server-to-facilitator request to batch on-chain claims of accumulated vouchers. `claimAuthorizerSignature` is optional; when absent the facilitator auto-signs with its receiver-authorizer key.
      properties:
        type:
          type: string
          description: The payload-type discriminator. Must be `"claim"` for a server-to-facilitator on-chain claim batch request.
          enum:
            - claim
        claims:
          type: array
          description: The list of voucher claims to batch in a single on-chain `claim` call.
          items:
            $ref: '#/components/schemas/x402BatchSettlementClaim'
        claimAuthorizerSignature:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          description: Optional EIP-712 signature from the receiver authorizer over the claim batch. When omitted, the facilitator auto-signs.
      required:
        - type
        - claims
      example:
        type: claim
        claims:
          - voucher:
              channel:
                payer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
                payerAuthorizer: '0x857b06519E91e3A54538791bDbb0E22373e36b66'
                receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
                receiverAuthorizer: '0x1111111111111111111111111111111111111111'
                token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                withdrawDelay: 86400
                salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
              maxClaimableAmount: '5000000'
            signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
            totalClaimed: '3000000'
    x402BatchSettlementSettlePayload:
      type: object
      title: x402BatchSettlementSettlePayload
      description: Server-to-facilitator request to transfer claimed funds for a `(receiver, token)` pair to the receiver wallet.
      properties:
        type:
          type: string
          description: The payload-type discriminator. Must be `"settle"` for a server-to-facilitator request to move claimed funds to the receiver.
          enum:
            - settle
        receiver:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address of the receiver to settle to.
          example: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
        token:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address of the token to settle.
          example: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
      required:
        - type
        - receiver
        - token
      example:
        type: settle
        receiver: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
        token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
    x402BatchSettlementEvmPayload:
      type: object
      title: x402BatchSettlementEvmPayload
      description: |-
        The x402 protocol batch-settlement scheme payload for EVM networks. The `batch-settlement` scheme uses pre-funded payment channels with off-chain cumulative-ceiling vouchers, allowing servers to batch-claim accumulated value in a single on-chain transaction. The payload is a discriminated union on the `type` field with five variants:

          - `deposit`: client-initiated channel funding via ERC-3009.
          - `voucher`: client-side cumulative voucher against an already-funded channel.
          - `refund`: cooperative refund request. The client emits a minimal shape (just channelConfig + voucher, with an optional `amount`); a mediating server enriches it with `amount`, `refundNonce`, and `claims` before forwarding to the facilitator. Authorizer signatures are optional — the facilitator auto-signs when absent.
          - `claim`: server-to-facilitator request to batch on-chain voucher claims.
          - `settle`: server-to-facilitator request to transfer claimed funds to the receiver.

        For more details, see [batch-settlement specs](https://github.com/x402-foundation/x402/tree/main/specs/schemes/batch-settlement).
      oneOf:
        - $ref: '#/components/schemas/x402BatchSettlementDepositPayload'
        - $ref: '#/components/schemas/x402BatchSettlementVoucherPayload'
        - $ref: '#/components/schemas/x402BatchSettlementRefundPayload'
        - $ref: '#/components/schemas/x402BatchSettlementClaimPayload'
        - $ref: '#/components/schemas/x402BatchSettlementSettlePayload'
      discriminator:
        propertyName: type
        mapping:
          deposit: '#/components/schemas/x402BatchSettlementDepositPayload'
          voucher: '#/components/schemas/x402BatchSettlementVoucherPayload'
          refund: '#/components/schemas/x402BatchSettlementRefundPayload'
          claim: '#/components/schemas/x402BatchSettlementClaimPayload'
          settle: '#/components/schemas/x402BatchSettlementSettlePayload'
    x402V2PaymentPayload:
      type: object
      title: x402V2PaymentPayload
      description: The x402 v2 protocol payment payload. Uses CAIP-2 network identifiers. The `accepted` field carries the full payment requirements; `scheme` and `network` are not top-level fields (they are on the nested `accepted` object).
      properties:
        x402Version:
          allOf:
            - $ref: '#/components/schemas/X402Version'
          description: The x402 protocol version. Must be `2` for this payload shape.
        payload:
          type: object
          description: 'The payload of the payment depending on the x402Version, scheme, and network. Discriminated by scheme-specific fields: exact-EVM/upto-EVM payloads carry a `signature`; exact-Solana carries a `transaction`; batch-settlement carries a `type` discriminator. See `x402BatchSettlementEvmPayload` for the documented batch-settlement variants.'
          oneOf:
            - $ref: '#/components/schemas/x402ExactEvmPayload'
            - $ref: '#/components/schemas/x402ExactEvmPermit2Payload'
            - $ref: '#/components/schemas/x402ExactSolanaPayload'
            - $ref: '#/components/schemas/x402UptoEvmPermit2Payload'
            - $ref: '#/components/schemas/x402BatchSettlementEvmPayload'
          example:
            signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
            authorization:
              from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              value: '1000000000000000000'
              validAfter: '1716150000'
              validBefore: '1716150000'
              nonce: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        accepted:
          $ref: '#/components/schemas/x402V2PaymentRequirements'
        resource:
          $ref: '#/components/schemas/x402ResourceInfo'
        extensions:
          type: object
          description: Optional protocol extensions.
          additionalProperties: true
          example:
            bazaar:
              info:
                input:
                  type: http
                  method: GET
              schema: {}
      example:
        x402Version: 2
        accepted:
          scheme: exact
          network: eip155:84532
          asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
          amount: '1000'
          payTo: '0x122F8Fcaf2152420445Aa424E1D8C0306935B5c9'
          maxTimeoutSeconds: 60
          extra:
            name: USDC
            version: '2'
        payload:
          signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
          authorization:
            from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            value: '1000000000000000000'
            validAfter: '1716150000'
            validBefore: '1716150000'
            nonce: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        resource:
          url: https://api.example.com/premium/resource/123
          description: Premium API access for data analysis.
          mimeType: application/json
      required:
        - x402Version
        - accepted
        - payload
    x402V1PaymentPayload:
      type: object
      title: x402V1PaymentPayload
      description: The x402 v1 protocol payment payload. Uses human-readable network names and requires `scheme` and `network` alongside the inner `payload` object.
      properties:
        x402Version:
          allOf:
            - $ref: '#/components/schemas/X402Version'
          description: The x402 protocol version. Must be `1` for this payload shape.
        scheme:
          type: string
          description: The scheme of the payment protocol to use. Currently, the only supported scheme is `exact`.
          enum:
            - exact
          example: exact
        network:
          allOf:
            - $ref: '#/components/schemas/X402V1Network'
          description: The network of the blockchain to send payment on.
          example: base
        payload:
          type: object
          description: The payload of the payment depending on the x402Version, scheme, and network.
          oneOf:
            - $ref: '#/components/schemas/x402ExactEvmPayload'
            - $ref: '#/components/schemas/x402ExactEvmPermit2Payload'
            - $ref: '#/components/schemas/x402ExactSolanaPayload'
          example:
            signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
            authorization:
              from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              value: '1000000000000000000'
              validAfter: '1716150000'
              validBefore: '1716150000'
              nonce: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
      example:
        x402Version: 1
        scheme: exact
        network: base
        payload:
          signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
          authorization:
            from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            value: '1000000000000000000'
            validAfter: '1716150000'
            validBefore: '1716150000'
            nonce: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
      required:
        - x402Version
        - scheme
        - network
        - payload
    x402PaymentPayload:
      type: object
      description: |-
        The x402 protocol payment payload that the client attaches to x402-paid API requests to the resource server in the PAYMENT-SIGNATURE header.
        For EVM networks, smart account signatures can be longer than 65 bytes.
      oneOf:
        - $ref: '#/components/schemas/x402V2PaymentPayload'
        - $ref: '#/components/schemas/x402V1PaymentPayload'
    EvmAccount:
      type: object
      properties:
        address:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum EVM address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        name:
          type: string
          description: |-
            An optional name for the account.
            Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
            Account names are guaranteed to be unique across all EVM accounts in the developer's CDP Project.
          example: my-account
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
        policies:
          type: array
          x-audience: public
          description: The list of policy IDs that apply to the account. This will include both the project-level policy and the account-level policy, if one exists.
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example:
            - 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          description: The UTC ISO 8601 timestamp at which the account was created.
          example: '2025-03-25T12:00:00Z'
          format: date-time
        updatedAt:
          type: string
          description: The UTC ISO 8601 timestamp at which the account was last updated.
          example: '2025-03-26T12:00:00Z'
          format: date-time
      required:
        - address
    EvmEip7702DelegationOperation:
      type: object
      description: The status of an EIP-7702 delegation operation.
      properties:
        delegationOperationId:
          type: string
          format: uuid
          description: The unique identifier for the delegation operation.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          description: |-
            The current status of the delegation operation.
            UNSPECIFIED means the status has not been set. PENDING means the operation has been created but not yet submitted. SUBMITTED means the operation has been submitted to the network. COMPLETED means the operation has completed successfully. FAILED means the operation has failed.
          enum:
            - UNSPECIFIED
            - PENDING
            - SUBMITTED
            - COMPLETED
            - FAILED
          example: COMPLETED
        transactionHash:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
          description: The hash of the delegation transaction, if available. Present once the transaction has been submitted to the network.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        network:
          $ref: '#/components/schemas/EvmEip7702DelegationNetwork'
        delegateAddress:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The address the account has delegated to, if any. Only present when the account has an active delegation.
          example: '0x7702cb554e6bFb442cb743A7dF23154544a7176C'
      required:
        - delegationOperationId
        - status
        - network
    EvmSmartAccount:
      type: object
      properties:
        address:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The 0x-prefixed, checksum address of the Smart Account.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        owners:
          type: array
          items:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
          description: Today, only a single owner can be set for a Smart Account, but this is an array to allow having multiple owners in the future. The address is a 0x-prefixed, checksum address.
          example:
            - '0xfc807D1bE4997e5C7B33E4d8D57e60c5b0f02B1a'
        name:
          type: string
          description: |-
            An optional name for the account.
            Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
            Account names are guaranteed to be unique across all Smart Accounts in the developer's CDP Project.
          example: my-smart-account
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
        policies:
          type: array
          x-audience: public
          description: The list of policy IDs that apply to the smart account. This will include both the project-level policy and the account-level policy, if one exists.
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example:
            - 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          description: The UTC ISO 8601 timestamp at which the account was created.
          example: '2025-03-25T12:00:00Z'
          format: date-time
        updatedAt:
          type: string
          description: The UTC ISO 8601 timestamp at which the account was last updated.
          example: '2025-03-26T12:00:00Z'
          format: date-time
      required:
        - address
        - owners
    SpendPermissionNetwork:
      type: string
      description: The network the spend permission is on.
      enum:
        - base
        - base-sepolia
        - ethereum
        - ethereum-sepolia
        - optimism
        - arbitrum
        - avalanche
        - polygon
      example: base
    CreateSpendPermissionRequest:
      type: object
      description: Request parameters for creating a Spend Permission.
      properties:
        network:
          $ref: '#/components/schemas/SpendPermissionNetwork'
        spender:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Entity that can spend account's tokens. Can be either a Smart Account or an EOA.
          example: '0x9Fb909eA400c2b8D99Be292DADf07e63B814527c'
        token:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: ERC-7528 native token address (e.g. "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" for native ETH), or an  ERC-20 contract address.
          example: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
        allowance:
          type: string
          description: Maximum allowed value to spend, in atomic units for the specified token, within each period.
          example: '1000000000000000000'
        period:
          type: string
          description: Time duration for resetting used allowance on a recurring basis (seconds).
          example: '86400'
        start:
          type: string
          description: The start time for this spend permission, in Unix seconds.
          example: '0'
        end:
          type: string
          description: The expiration time for this spend permission, in Unix seconds.
          example: '281474976710655'
        salt:
          type: string
          description: An arbitrary salt to differentiate unique spend permissions with otherwise identical data.
          example: '95959551014433038874972658238091428449162862973207257628575040053304171156143'
        extraData:
          type: string
          description: Arbitrary data to include in the permission.
          example: 0x
        paymasterUrl:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: The paymaster URL of the spend permission.
          example: https://paymaster.cdp.coinbase.com
      required:
        - network
        - spender
        - token
        - allowance
        - period
        - start
        - end
    SpendPermission:
      type: object
      description: The core spend permission.
      example:
        account: '0xd53Ee96438383Bb1eff07958D110B81363E9Ab47'
        spender: '0x9Fb909eA400c2b8D99Be292DADf07e63B814527c'
        token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
        allowance: '1000000000000000000'
        period: '86400'
        start: '0'
        end: '281474976710655'
        salt: '0'
        extraData: 0x
      properties:
        account:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Smart account this spend permission is valid for.
          example: '0xd53Ee96438383Bb1eff07958D110B81363E9Ab47'
        spender:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Entity that can spend account's tokens.
          example: '0x9Fb909eA400c2b8D99Be292DADf07e63B814527c'
        token:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Token address (ERC-7528 native token address or ERC-20 contract).
          example: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
        allowance:
          type: string
          description: Maximum allowed value to spend, in atomic units for the specified token, within each period.
          example: '1000000000000000000'
        period:
          type: string
          description: Time duration for resetting used allowance on a recurring basis (seconds).
          example: '86400'
        start:
          type: string
          description: The start time for this spend permission, in Unix seconds.
          example: '0'
        end:
          type: string
          description: The expiration time for this spend permission, in Unix seconds.
          example: '281474976710655'
        salt:
          type: string
          description: An arbitrary salt to differentiate unique spend permissions with otherwise identical data.
          example: '0'
        extraData:
          type: string
          description: Arbitrary data to include in the permission.
          example: 0x
      required:
        - account
        - spender
        - token
        - allowance
        - period
        - start
        - end
        - salt
        - extraData
    SpendPermissionResponseObject:
      type: object
      properties:
        permission:
          $ref: '#/components/schemas/SpendPermission'
        permissionHash:
          type: string
          description: Unique hash identifier for this permission.
          example: '0x62bc94756bb6221a7913beab6024171fc60d3380fdc06759bfac76e8ccb3f63d'
        revoked:
          type: boolean
          description: Whether this permission has been revoked.
          example: false
        revokedAt:
          type: string
          description: The UTC ISO 8601 timestamp when the permission was revoked (if applicable).
          example: '2025-03-25T12:00:00Z'
          format: date-time
        createdAt:
          type: string
          description: The UTC ISO 8601 timestamp when the permission was created.
          example: '2025-03-25T12:00:00Z'
          format: date-time
        network:
          $ref: '#/components/schemas/SpendPermissionNetwork'
      required:
        - permission
        - permissionHash
        - revoked
        - createdAt
        - network
    RevokeSpendPermissionRequest:
      type: object
      description: Request parameters for revoking a Spend Permission.
      properties:
        network:
          $ref: '#/components/schemas/SpendPermissionNetwork'
        permissionHash:
          type: string
          description: The hash of the spend permission to revoke.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        paymasterUrl:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: The paymaster URL of the spend permission.
          example: https://paymaster.cdp.coinbase.com
      required:
        - network
        - permissionHash
    EvmSwapsNetwork:
      type: string
      enum:
        - base
        - ethereum
        - arbitrum
        - optimism
        - polygon
      description: The network on which to perform the swap.
      example: base
    toToken:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: The 0x-prefixed contract address of the token to receive.
      example: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607'
    fromToken:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: The 0x-prefixed contract address of the token to send.
      example: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
    fromAmount:
      type: string
      pattern: ^\d+$
      description: The amount of the `fromToken` to send in atomic units of the token. For example, `1000000000000000000` when sending ETH equates to 1 ETH, `1000000` when sending USDC equates to 1 USDC, etc.
      example: '1000000000000000000'
    taker:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: The 0x-prefixed address that holds the `fromToken` balance and has the `Permit2` allowance set for the swap.
      example: '0xAc0974bec39a17e36ba4a6b4d238ff944bacb478'
    signerAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: The 0x-prefixed Externally Owned Account (EOA) address that will sign the `Permit2` EIP-712 permit message. This is only needed if `taker` is a smart contract.
      example: '0x922f49447d8a07e3bd95bd0d56f35241523fbab8'
    gasPrice:
      type: string
      pattern: ^\d+$
      description: The target gas price for the swap transaction, in Wei. For EIP-1559 transactions, this value should be seen as the `maxFeePerGas` value. If not provided, the API will use an estimate based on the current network conditions.
      example: '1000000000'
    slippageBps:
      type: integer
      minimum: 0
      maximum: 10000
      description: The maximum acceptable slippage of the `toToken` in basis points. If this parameter is set to 0, no slippage will be tolerated. If not provided, the default slippage tolerance is 100 bps (i.e., 1%).
      default: 100
      example: 100
    TokenFee:
      type: object
      properties:
        amount:
          type: string
          pattern: ^\d+$
          description: The estimated amount of the fee in atomic units of the `token`. For example, `1000000000000000` if the fee is in ETH equates to 0.001 ETH, `10000` if the fee is in USDC equates to 0.01 USDC, etc.
          example: '1000000000000000000'
        token:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: The contract address of the token that the fee is paid in. The address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` is used for the native token of the network (e.g. ETH).
          example: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
      required:
        - amount
        - token
    CommonSwapResponseIssuesAllowance:
      type: object
      properties:
        currentAllowance:
          type: string
          pattern: ^\d+$
          description: The current allowance of the `fromToken` by the `taker`.
          example: '1000000000'
        spender:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: The 0x-prefixed address of to set the allowance on.
          example: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
      required:
        - currentAllowance
        - spender
      example:
        currentAllowance: '1000000000'
        spender: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
    CommonSwapResponseIssuesBalance:
      type: object
      properties:
        token:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: The 0x-prefixed contract address of the token.
        currentBalance:
          type: string
          pattern: ^\d+$
          description: The current balance of the `fromToken` by the `taker`.
          example: '10000000'
        requiredBalance:
          type: string
          pattern: ^\d+$
          description: The amount of the token that the `taker` must hold.
          example: '1000000000000000000'
      required:
        - token
        - currentBalance
        - requiredBalance
      example:
        token: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
        currentBalance: '1000000000000000000'
        requiredBalance: '1000000000000000000'
    CommonSwapResponse:
      type: object
      properties:
        blockNumber:
          type: string
          pattern: ^[1-9]\d*$
          description: The block number at which the liquidity conditions were examined.
          example: '17038723'
        toAmount:
          type: string
          pattern: ^(0|[1-9]\d*)$
          description: The amount of the `toToken` that will be received in atomic units of the `toToken`. For example, `1000000000000000000` when receiving ETH equates to 1 ETH, `1000000` when receiving USDC equates to 1 USDC, etc.
          example: '1000000000000000000'
        toToken:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: The 0x-prefixed contract address of the token that will be received.
          example: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607'
        fees:
          type: object
          description: The estimated fees for the swap.
          properties:
            gasFee:
              x-go-type: '*TokenFee'
              description: The estimated gas fee for the swap.
              oneOf:
                - $ref: '#/components/schemas/TokenFee'
                - type: 'null'
            protocolFee:
              x-go-type: '*TokenFee'
              description: The estimated protocol fee for the swap.
              oneOf:
                - $ref: '#/components/schemas/TokenFee'
                - type: 'null'
          required:
            - gasFee
            - protocolFee
          example:
            gasFee:
              amount: '1000000000000000000'
              token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
            protocolFee:
              amount: '1000000000000000000'
              token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
        issues:
          type: object
          description: An object containing potential issues discovered during validation that could prevent the swap from being executed successfully.
          properties:
            allowance:
              x-go-type: '*CommonSwapResponseIssuesAllowance'
              description: Details of the allowances that the taker must set in order to execute the swap successfully. Null if no allowance is required.
              oneOf:
                - $ref: '#/components/schemas/CommonSwapResponseIssuesAllowance'
                - type: 'null'
            balance:
              x-go-type: '*CommonSwapResponseIssuesBalance'
              description: Details of the balance of the `fromToken` that the `taker` must hold. Null if the `taker` has a sufficient balance.
              oneOf:
                - $ref: '#/components/schemas/CommonSwapResponseIssuesBalance'
                - type: 'null'
            simulationIncomplete:
              type: boolean
              description: This is set to true when the transaction cannot be validated. This can happen when the taker has an insufficient balance of the `fromToken`. Note that this does not necessarily mean that the trade will revert.
              example: false
          required:
            - allowance
            - balance
            - simulationIncomplete
          example:
            allowance:
              currentAllowance: '1000000000'
              spender: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
            balance:
              token: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
              currentBalance: '900000000000000000'
              requiredBalance: '1000000000000000000'
            simulationIncomplete: false
        liquidityAvailable:
          type: boolean
          enum:
            - true
          description: Whether sufficient liquidity is available to settle the swap. All other fields in the response will be empty if this is false.
          example: true
        minToAmount:
          type: string
          pattern: ^(0|[1-9]\d*)$
          description: The minimum amount of the `toToken` that must be received for the swap to succeed, in atomic units of the `toToken`.  For example, `1000000000000000000` when receiving ETH equates to 1 ETH, `1000000` when receiving USDC equates to 1 USDC, etc. This value is influenced by the `slippageBps` parameter.
          example: '900000000000000000'
        fromAmount:
          type: string
          pattern: ^(0|[1-9]\d*)$
          description: The amount of the `fromToken` that will be sent in this swap, in atomic units of the `fromToken`. For example, `1000000000000000000` when sending ETH equates to 1 ETH, `1000000` when sending USDC equates to 1 USDC, etc.
          example: '1000000000000000000'
        fromToken:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: The 0x-prefixed contract address of the token that will be sent.
          example: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
      required:
        - blockNumber
        - toAmount
        - toToken
        - fees
        - issues
        - liquidityAvailable
        - minToAmount
        - fromAmount
        - fromToken
      example:
        blockNumber: '17038723'
        toAmount: '1000000000000000000'
        toToken: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607'
        fees:
          gasFee:
            amount: '1000000000000000000'
            token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
          protocolFee:
            amount: '1000000000000000000'
            token: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
        issues:
          allowance:
            currentAllowance: '1000000000'
            spender: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
          balance:
            token: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
            currentBalance: '1000000000000000000'
            requiredBalance: '1000000000000000000'
          simulationIncomplete: false
        liquidityAvailable: true
        minToAmount: '900000000000000000'
        fromAmount: '1000000000000000000'
        fromToken: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
    GetSwapPriceResponse:
      title: GetSwapPriceResponse
      allOf:
        - $ref: '#/components/schemas/CommonSwapResponse'
        - type: object
          properties:
            gas:
              x-go-type: '*string'
              description: The estimated gas limit that should be used to send the transaction to guarantee settlement.
              oneOf:
                - type: string
                  pattern: ^\d+$
                - type: 'null'
              example: '100000'
            gasPrice:
              type: string
              pattern: ^\d+$
              description: The gas price, in Wei, that should be used to send the transaction. For EIP-1559 transactions, this value should be seen as the `maxFeePerGas` value. The transaction should be sent with this gas price to guarantee settlement.
              example: '1000000000'
          required:
            - gas
            - gasPrice
    SwapUnavailableResponse:
      type: object
      title: SwapUnavailableResponse
      properties:
        liquidityAvailable:
          type: boolean
          enum:
            - false
          description: Whether sufficient liquidity is available to settle the swap. All other fields in the response will be empty if this is false.
          example: false
      required:
        - liquidityAvailable
      example:
        liquidityAvailable: false
    GetSwapPriceResponseWrapper:
      description: A wrapper for the response of a swap price operation.
      oneOf:
        - $ref: '#/components/schemas/GetSwapPriceResponse'
        - $ref: '#/components/schemas/SwapUnavailableResponse'
    SwapPermit2Approval:
      type: object
      properties:
        hash:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
          description: The hash for the approval according to [EIP-712](https://eips.ethereum.org/EIPS/eip-712). Computing the hash of the `eip712` field should match the value of this field.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        eip712:
          $ref: '#/components/schemas/EIP712Message'
      required:
        - hash
        - eip712
    CreateSwapQuoteResponse:
      title: CreateSwapQuoteResponse
      allOf:
        - type: object
          properties:
            permit2:
              x-go-type: '*SwapPermit2Approval'
              description: The approval object which contains the necessary fields to submit an approval for this transaction. Null if the `fromToken` is the native token or the transaction is a native token wrap / unwrap.
              oneOf:
                - $ref: '#/components/schemas/SwapPermit2Approval'
                - type: 'null'
            transaction:
              type: object
              description: The details of the transaction to be signed and submitted to execute the swap.
              properties:
                to:
                  type: string
                  pattern: ^0x[a-fA-F0-9]{40}$
                  description: The 0x-prefixed address of the contract to call.
                  example: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
                data:
                  type: string
                  description: The hex-encoded call data to send to the contract.
                  example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                gas:
                  type: string
                  pattern: ^\d+$
                  description: The estimated gas limit that should be used to send the transaction to guarantee settlement.
                  example: '100000'
                gasPrice:
                  type: string
                  pattern: ^\d+$
                  description: The gas price, in Wei, that should be used to send the transaction. For EIP-1559 transactions, this value should be seen as the `maxFeePerGas` value. The transaction should be sent with this gas price to guarantee settlement.
                  example: '1000000000'
                value:
                  type: string
                  pattern: ^\d+$
                  description: The value of the transaction in Wei.
                  example: '1000000000000000000'
              required:
                - to
                - data
                - gas
                - gasPrice
                - value
          required:
            - permit2
            - transaction
        - $ref: '#/components/schemas/CommonSwapResponse'
    CreateSwapQuoteResponseWrapper:
      description: A wrapper for the response of a swap quote operation.
      oneOf:
        - $ref: '#/components/schemas/CreateSwapQuoteResponse'
        - $ref: '#/components/schemas/SwapUnavailableResponse'
    ListEvmTokenBalancesNetwork:
      type: string
      enum:
        - base
        - base-sepolia
        - ethereum
      description: The name of the supported EVM networks in human-readable format.
      example: base
    TokenAmount:
      type: object
      description: Amount of a given token.
      example:
        amount: '125000000000000000000'
        decimals: 18
      properties:
        amount:
          type: string
          pattern: ^[0-9]+$
          description: The amount is denominated in the smallest indivisible unit of the token. For ETH, the smallest indivisible unit is Wei (10^-18 ETH). For ERC-20s, the smallest unit is the unit returned from `function totalSupply() public view returns (uint256)`.
          example: '1250000000000000000'
        decimals:
          type: integer
          format: int64
          description: |-
            'decimals' is the exponential value N that satisfies the equation `amount * 10^-N = standard_denomination`. The standard denomination is the most commonly used denomination for the token.
            - In the case of the native gas token, `decimals` is defined via convention. As an example, for ETH of Ethereum mainnet, the standard denomination is 10^-18 the smallest denomination (Wei). As such, for ETH on Ethereum mainnet, `decimals` is 18. - In the case of ERC-20 tokens, `decimals` is defined via configuration. `decimals` will be the number returned by `function decimals() public view returns (uint8)` on the underlying token contract.
            Not all tokens have a `decimals` field, as this function is [optional in the ERC-20 specification](https://eips.ethereum.org/EIPS/eip-20#decimals). This field will be left empty if the underlying token contract doesn't implement `decimals`.
            Further, this endpoint will only populate this value for a small subset of whitelisted ERC-20 tokens at this time. We intend to improve coverage in the future.
          example: 18
      required:
        - amount
        - decimals
    Token:
      type: object
      description: General information about a token. Includes the type, the network, and other identifying information.
      example:
        network: base
        symbol: ETH
        name: Ether
        contractAddress: '0x1234567890123456789012345678901234567890'
      properties:
        network:
          $ref: '#/components/schemas/ListEvmTokenBalancesNetwork'
        symbol:
          type: string
          description: |-
            The symbol of this token (ex: SOL, ETH, USDC).
            The token symbol is not unique. It is possible for two different tokens to have the same symbol.
            For native gas tokens, this symbol is defined via convention. As an example, for ETH on Ethereum mainnet, the symbol is "ETH". For ERC-20 tokens, this symbol is defined via configuration. `symbol` will be the string returned by `function symbol() public view returns (string)` on the underlying token contract.
            Not all tokens have a symbol, as this function is [optional in the ERC-20 specification](https://eips.ethereum.org/EIPS/eip-20#symbol). This field will only be populated when the token's underlying ERC-20 contract has a `symbol()` function.
            Further, this endpoint will only populate this value for a small subset of whitelisted ERC-20 tokens at this time. We intend to improve coverage in the future.
          example: ETH
        name:
          type: string
          description: |-
            The name of this token (ex: "Solana", "Ether", "USD Coin").
            The token name is not unique. It is possible for two different tokens to have the same name.
            For native gas tokens, this name is defined via convention. As an example, for ETH on Ethereum mainnet, the name is "Ether". For ERC-20 tokens, this name is defined via configuration. `name` will be the string returned by `function name() public view returns (string)` on the underlying token contract.
            Not all tokens have a name, as this function is [optional in the ERC-20 specification](https://eips.ethereum.org/EIPS/eip-20#name). This field will only be populated when the token's underlying ERC-20 contract has a `name()` function.
            Further, this endpoint will only populate this value for a small subset of whitelisted ERC-20 tokens at this time. We intend to improve coverage in the future.
          example: Ether
        contractAddress:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
          description: |-
            The contract address of the token.
            For Ether, the contract address is `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` per [EIP-7528](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7528.md). For ERC-20 tokens, this is the contract address where the token is deployed.
          example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
      required:
        - network
        - contractAddress
    TokenBalance:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/TokenAmount'
        token:
          $ref: '#/components/schemas/Token'
      required:
        - amount
        - token
    EthValueCriterion:
      type: object
      title: EthValueCriterion
      description: A schema for specifying a criterion for the `value` field of an EVM transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `ethValue`.
          example: ethValue
          enum:
            - ethValue
        ethValue:
          type: string
          pattern: ^[0-9]+$
          maxLength: 78
          description: The amount of ETH, in wei, that the transaction's `value` field should be compared to.
          example: '1000000000000000000'
        operator:
          type: string
          description: The operator to use for the comparison. The transaction's `value` field will be on the left-hand side of the operator, and the `ethValue` field will be on the right-hand side.
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          example: <=
      required:
        - type
        - ethValue
        - operator
    EvmAddressCriterion:
      type: object
      x-audience: public
      title: EvmAddressCriterion
      description: A schema for specifying a criterion for the `to` field of an EVM transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `evmAddress`.
          example: evmAddress
          enum:
            - evmAddress
        addresses:
          type: array
          description: A list of 0x-prefixed EVM addresses that the transaction's `to` field should be compared to. There is a limit of 300 addresses per criterion.
          items:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            description: The 0x-prefixed EVM address that the transaction's `to` field should be compared to.
          example:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            - '0x1234567890123456789012345678901234567890'
        operator:
          type: string
          description: The operator to use for the comparison. The transaction's `to` field will be on the left-hand side of the operator, and the `addresses` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - addresses
        - operator
    KnownAbiType:
      type: string
      title: KnownAbiType
      description: |-
        A reference to an established EIP standard. When referencing a `KnownAbiType` within a policy rule configuring an `EvmDataCriterion`, criteria will only decode function data officially documented in the standard. For more information on supported token standards, see the links below.
          - [erc20 - Token Standard](https://eips.ethereum.org/EIPS/eip-20).
          - [erc721 - Non-Fungible Token Standard](https://eips.ethereum.org/EIPS/eip-721).
          - [erc1155 - Multi Token Standard](https://eips.ethereum.org/EIPS/eip-1155).
      enum:
        - erc20
        - erc721
        - erc1155
    AbiParameter:
      x-audience: public
      type: object
      description: Parameter definition for ABI functions, errors, and constructors.
      required:
        - type
      properties:
        name:
          type: string
          description: The name of the parameter.
          example: tokenId
        type:
          type: string
          description: The canonical type of the parameter.
          example: uint256
        internalType:
          type: string
          description: The internal Solidity type used by the compiler.
          example: uint256
        components:
          type: array
          description: Used for tuple types.
          items:
            $ref: '#/components/schemas/AbiParameter'
          example:
            - name: x
              type: uint256
      example:
        name: tokenId
        type: uint256
        internalType: uint256
    AbiStateMutability:
      x-audience: public
      type: string
      description: State mutability of a function in Solidity.
      enum:
        - pure
        - view
        - nonpayable
        - payable
      example: view
    AbiFunction:
      x-audience: public
      type: object
      title: AbiFunction
      description: ABI function type for contract functions.
      required:
        - type
        - name
        - inputs
        - outputs
        - stateMutability
      properties:
        type:
          description: The type of the ABI item, must be `function`.
          type: string
          enum:
            - function
          example: function
        name:
          type: string
          description: The name of the ABI function.
          example: approve
        inputs:
          type: array
          description: The list of ABI parameters used for this function.
          items:
            $ref: '#/components/schemas/AbiParameter'
          example:
            - name: spender
              type: address
              internalType: address
        outputs:
          type: array
          description: The values returned by this function.
          items:
            $ref: '#/components/schemas/AbiParameter'
          example:
            name: ''
            type: bool
            internalType: bool
        constant:
          type: boolean
          description: Deprecated. Use pure or view from stateMutability instead.
          example: false
        payable:
          type: boolean
          description: Deprecated. Use payable or nonpayable from `stateMutability` instead.
          example: false
        stateMutability:
          $ref: '#/components/schemas/AbiStateMutability'
        gas:
          type: integer
          description: Deprecated. Vyper used to provide gas estimates.
          example: 0
      example:
        type: function
        name: balanceOf
        inputs:
          - name: owner
            type: address
            internalType: address
        outputs:
          - name: null
            type: uint256
            internalType: uint256
        stateMutability: view
    AbiInput:
      x-audience: public
      type: object
      title: AbiInput
      description: Generic ABI item type encapsulating all other types besides `function`.
      required:
        - type
      properties:
        type:
          description: The type of the ABI item.
          type: string
          enum:
            - constructor
            - error
            - event
            - fallback
            - receive
          example: constructor
        additionalProperties:
          description: For additional information on the ABI JSON specification, see [the Solidity documentation](https://docs.soliditylang.org/en/latest/abi-spec.html#json).
          example:
            type: error
            name: ERC20InvalidSpender
            inputs:
              - name: spender
                type: address
                internalType: address
    Abi:
      x-audience: public
      type: array
      description: Contract ABI Specification following Solidity's external JSON interface format.
      items:
        oneOf:
          - $ref: '#/components/schemas/AbiFunction'
          - $ref: '#/components/schemas/AbiInput'
      example:
        - type: function
          name: approve
          inputs:
            - name: spender
              type: address
              internalType: address
            - name: amount
              type: uint256
              internalType: uint256
          outputs:
            - name: null
              type: bool
              internalType: bool
          stateMutability: nonpayable
        - type: event
          name: Transfer
          inputs:
            - name: from
              type: address
              indexed: true
              internalType: address
          anonymous: false
        - type: error
          name: ERC20InvalidSpender
          inputs:
            - name: spender
              type: address
              internalType: address
    EvmDataParameterCondition:
      x-audience: public
      type: object
      title: EvmDataParameterCondition
      properties:
        name:
          type: string
          example: to
          description: The name of the parameter to check against a transaction's calldata. If name is unknown, or is not named, you may supply an array index, e.g., `0` for first parameter.
        operator:
          type: string
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          description: The operator to use for the comparison. The value resolved at the `name` will be on the left-hand side of the operator, and the `value` field will be on the right-hand side.
          example: '=='
        value:
          type: string
          example: '100000'
          description: A single value to compare the value resolved at `name` to. All values are encoded as strings. Refer to the table in the documentation for how values should be encoded, and which operators are supported for each type.
      required:
        - name
        - operator
        - value
    EvmDataParameterConditionList:
      x-audience: public
      type: object
      title: EvmDataParameterConditionList
      properties:
        name:
          type: string
          example: to
          description: The name of the parameter to check against a transaction's calldata. If name is unknown, or is not named, you may supply an array index, e.g., `0` for first parameter.
        operator:
          type: string
          enum:
            - in
            - not in
          description: The operator to use for the comparison. The value resolved at the `name` will be on the left-hand side of the operator, and the `values` field will be on the right-hand side.
          example: in
        values:
          type: array
          items:
            type: string
            example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            description: A single potential value to compare against the resolved `name` value. All values are encoded as strings. Refer to the table in the documentation for how values should be encoded, and which operators are supported for each type.
          description: Values to compare against the resolved `name` value. All values are encoded as strings. Refer to the table in the documentation for how values should be encoded, and which operators are supported for each type.
          example:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      required:
        - name
        - operator
        - values
    EvmDataCondition:
      type: object
      x-audience: public
      description: A single condition to apply against the function and encoded arguments in the transaction's `data` field. Each `parameter` configuration must be successfully evaluated against the corresponding function argument in order for a policy to be accepted.
      properties:
        function:
          type: string
          example: transfer
          description: The name of a smart contract function being called.
        params:
          type: array
          description: An optional list of parameter conditions to apply against encoded arguments in the transaction's `data` field.
          items:
            description: A list of parameter conditions to apply against encoded arguments in the transaction's `data` field.
            oneOf:
              - $ref: '#/components/schemas/EvmDataParameterCondition'
              - $ref: '#/components/schemas/EvmDataParameterConditionList'
          example:
            - name: value
              operator: <=
              value: '10000'
            - name: to
              operator: in
              values:
                - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      example:
        function: transfer
        params:
          - name: value
            operator: <=
            value: '10000'
          - name: to
            operator: in
            values:
              - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      required:
        - function
    EvmDataCriterion:
      type: object
      x-audience: public
      title: EvmDataCriterion
      description: A schema for specifying a criterion for the `data` field of an EVM transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `evmData`.
          example: evmData
          enum:
            - evmData
        abi:
          description: The ABI of the smart contract being called. This can be a partial structure with only specific functions.
          oneOf:
            - $ref: '#/components/schemas/KnownAbiType'
            - $ref: '#/components/schemas/Abi'
          example: erc20
        conditions:
          type: array
          description: A list of conditions to apply against the function and encoded arguments in the transaction's `data` field. Each condition must be met in order for this policy to be accepted or rejected.
          items:
            $ref: '#/components/schemas/EvmDataCondition'
          example:
            - function: approve
            - function: transfer
              params:
                - name: value
                  operator: <=
                  value: '10000'
                - name: to
                  operator: in
                  values:
                    - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      required:
        - type
        - abi
        - conditions
    NetUSDChangeCriterion:
      type: object
      title: NetUSDChangeCriterion
      description: A schema for specifying a criterion for the USD denominated asset transfer or exposure for a transaction. This includes native transfers, as well as token transfers.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `netUSDChange`.
          example: netUSDChange
          enum:
            - netUSDChange
        changeCents:
          type: integer
          description: The amount of USD, in cents, that the total value of a transaction's asset transfer should be compared to.
          example: 10000
        operator:
          type: string
          description: The operator to use for the comparison. The total value of a transaction's asset transfer will be on the left-hand side of the operator, and the `changeCents` field will be on the right-hand side.
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          example: <=
      required:
        - type
        - changeCents
        - operator
    SignEvmTransactionCriteria:
      type: array
      description: A schema for specifying criteria for the SignEvmTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
    SignEvmTransactionRule:
      title: SignEvmTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEvmTransaction
          enum:
            - signEvmTransaction
        criteria:
          $ref: '#/components/schemas/SignEvmTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    EvmNetworkCriterion:
      type: object
      x-audience: public
      title: EvmNetworkCriterion
      description: A schema for specifying a criterion for the intended `network` of an EVM transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `evmNetwork`.
          example: evmNetwork
          enum:
            - evmNetwork
        networks:
          type: array
          description: A list of EVM network identifiers that the transaction's intended `network` should be compared to.
          items:
            type: string
            description: The network the transaction is for.
            enum:
              - base-sepolia
              - base
              - ethereum
              - ethereum-sepolia
              - avalanche
              - polygon
              - optimism
              - arbitrum
              - arbitrum-sepolia
              - zora
              - bnb
              - world
              - world-sepolia
            example: base-sepolia
          example:
            - base
            - ethereum
        operator:
          type: string
          description: The operator to use for the comparison. The transaction's intended `network` will be on the left-hand side of the operator, and the `networks` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - networks
        - operator
    SendEvmTransactionCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the SignEvmTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
    SendEvmTransactionRule:
      x-audience: public
      title: SendEvmTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendEvmTransaction
          enum:
            - sendEvmTransaction
        criteria:
          $ref: '#/components/schemas/SendEvmTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    EvmMessageCriterion:
      type: object
      x-audience: public
      title: EvmMessageCriterion
      description: A schema for specifying a criterion for the message being signed.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `evmMessage`.
          example: evmMessage
          enum:
            - evmMessage
        match:
          type: string
          description: A regular expression the message is matched against. Accepts valid regular expression syntax described by [RE2](https://github.com/google/re2/wiki/Syntax).
          example: ^hello ([a-z]+)$
      required:
        - type
        - match
    SignEvmMessageCriteria:
      x-audience: public
      type: array
      description: A schema for specifying the rejection criteria for the SignEvmMessage operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EvmMessageCriterion'
      example:
        - type: evmMessage
          match: ^hello ([a-z]+)$
    SignEvmMessageRule:
      x-audience: public
      title: SignEvmMessageRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEvmMessage
          enum:
            - signEvmMessage
        criteria:
          $ref: '#/components/schemas/SignEvmMessageCriteria'
      required:
        - action
        - operation
        - criteria
    EvmTypedAddressCondition:
      type: object
      x-audience: public
      title: EvmTypedAddressCondition
      description: A schema for specifying criterion for an address field of an EVM typed message. The address can be deeply nested within the typed data's message.
      properties:
        addresses:
          type: array
          description: A list of 0x-prefixed EVM addresses that the value located at the message's path should be compared to. There is a limit of 300 addresses per criterion.
          items:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            description: The 0x-prefixed EVM address that the value located at the message's path should be compared to.
          example:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            - '0x1234567890123456789012345678901234567890'
        operator:
          type: string
          description: The operator to use for the comparison. The value located at the message's path will be on the left-hand side of the operator, and the `addresses` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
        path:
          type: string
          description: The path to the field to compare against this criterion. To reference deeply nested fields within the message, separate object keys by `.`, and access array values using `[index]`. If the field does not exist or is not an address, the operation will be rejected.
          example: targets[0].address
      required:
        - addresses
        - operator
        - path
    EvmTypedNumericalCondition:
      type: object
      x-audience: public
      title: EvmTypedNumericalCondition
      description: A schema for specifying criterion for a numerical field of an EVM typed message. The value can be deeply nested within the typed data's message.
      properties:
        value:
          type: string
          pattern: ^[0-9]+$
          description: The amount that the value located at the message's path should be compared to.
          example: '1000000000000000000'
        operator:
          type: string
          description: The operator to use for the comparison. The value located at the message's path will be on the left-hand side of the operator, and the `value` field will be on the right-hand side.
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          example: <=
        path:
          type: string
          description: The path to the field to compare against this criterion. To reference deeply nested fields within the message, separate object keys by `.`, and access array values using `[index]`. If the field does not exist or is not an address, the operation will be rejected.
          example: targets[0].amount
      required:
        - value
        - operator
        - path
    EvmTypedStringCondition:
      type: object
      x-audience: public
      title: EvmTypedStringCondition
      description: A schema for specifying criterion for a string field of an EVM typed message. The value can be deeply nested within the typed data's message.
      properties:
        match:
          type: string
          description: A regular expression the field is matched against.
          example: ^hello ([a-z]+)$
        path:
          type: string
          description: The path to the field to compare against this criterion. To reference deeply nested fields within the message, separate object keys by `.`, and access array values using `[index]`. If the field does not exist or is not an address, the operation will be rejected.
          example: targets[0].message
      required:
        - match
        - path
    SignEvmTypedDataFieldCriterion:
      x-audience: public
      type: object
      title: SignEvmTypedDataFieldCriterion
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `evmTypedDataField`.
          example: evmTypedDataField
          enum:
            - evmTypedDataField
        types:
          type: object
          description: An object containing EIP-712 type definitions, as well as a primary type for the root message object.
          example:
            primaryType: Mail
            types:
              Person:
                - name: name
                  type: string
                - name: wallet
                  type: address
                - name: score
                  type: uint256
              Mail:
                - name: from
                  type: Person
                - name: to
                  type: Person
                - name: contents
                  type: string
          properties:
            types:
              type: object
              description: EIP-712 compliant map of model names to model definitions.
              additionalProperties:
                type: array
                description: Object containing names and types for fields within structured data.
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of a key within an EIP-712 data structure.
                    type:
                      type: string
                      description: The Solidity type of a value within an EIP-712 data structure.
            primaryType:
              type: string
              description: The name of the root EIP-712 type. This value must be included in the `types` object.
          required:
            - types
            - primaryType
        conditions:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/EvmTypedAddressCondition'
              - $ref: '#/components/schemas/EvmTypedNumericalCondition'
              - $ref: '#/components/schemas/EvmTypedStringCondition'
          description: A list of conditions to check against the data being signed. Each condition must be met for the rule to take effect.
          example:
            - addresses:
                - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              operator: in
              path: to.wallet
            - value: '50'
              operator: '>='
              path: to.score
            - match: ^hello ([a-z]+)$
              path: contents
      required:
        - type
        - types
        - conditions
    SignEvmTypedDataVerifyingContractCriterion:
      type: object
      x-audience: public
      title: SignEvmTypedDataVerifyingContractCriterion
      description: A schema for specifying criterion for a domain's verifying contract.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `evmTypedDataVerifyingContract`.
          example: evmTypedDataVerifyingContract
          enum:
            - evmTypedDataVerifyingContract
        addresses:
          type: array
          description: A list of 0x-prefixed EVM addresses that the domain's verifying contract should be compared to. There is a limit of 300 addresses per criterion.
          items:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            description: The 0x-prefixed EVM address that the domain's verifying contract should be compared to.
          example:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            - '0x1234567890123456789012345678901234567890'
        operator:
          type: string
          description: The operator to use for the comparison. The domain's verifying contract will be on the left-hand side of the operator, and the `addresses` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - addresses
        - operator
    SignEvmTypedDataCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the SignEvmTypedData operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SignEvmTypedDataFieldCriterion'
          - $ref: '#/components/schemas/SignEvmTypedDataVerifyingContractCriterion'
      example:
        - type: evmTypedDataField
          types:
            types:
              Person:
                - name: name
                  type: string
                - name: wallet
                  type: address
                - name: score
                  type: uint256
              Mail:
                - name: from
                  type: Person
                - name: to
                  type: Person
                - name: contents
                  type: string
            primaryType: Mail
          conditions:
            - addresses:
                - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              operator: in
              path: to.wallet
            - value: '50'
              operator: '>='
              path: to.score
            - match: ^hello ([a-z]+)$
              path: contents
        - type: evmTypedDataVerifyingContract
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
    SignEvmTypedDataRule:
      x-audience: public
      title: SignEvmTypedDataRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEvmTypedData
          enum:
            - signEvmTypedData
        criteria:
          $ref: '#/components/schemas/SignEvmTypedDataCriteria'
      required:
        - action
        - operation
        - criteria
    SolAddressCriterion:
      type: object
      title: SolAddressCriterion
      description: The criterion for the recipient addresses of a Solana transaction's native transfer instruction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `solAddress`.
          example: solAddress
          enum:
            - solAddress
        addresses:
          type: array
          description: The Solana addresses that are compared to the list of native transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array.
          items:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
            description: The Solana address that is compared to the list of native transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array.
          example:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        operator:
          type: string
          description: The operator to use for the comparison. Each of the native transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array will be on the left-hand side of the operator, and the `addresses` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - addresses
        - operator
    SolValueCriterion:
      x-audience: public
      type: object
      title: SolValueCriterion
      description: The criterion for the SOL value in lamports of a native transfer instruction in a Solana transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `solValue`.
          example: solValue
          enum:
            - solValue
        solValue:
          type: string
          description: The amount of SOL in lamports that the transaction instruction's `value` field should be compared to.
          example: '1000000000000000000'
        operator:
          type: string
          description: The operator to use for the comparison. The transaction instruction's `value` field will be on the left-hand side of the operator, and the `solValue` field will be on the right-hand side.
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          example: <=
      required:
        - type
        - solValue
        - operator
    SplAddressCriterion:
      x-audience: public
      type: object
      title: SplAddressCriterion
      description: The criterion for the recipient addresses of a Solana transaction's SPL token transfer instructions.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `splAddress`.
          example: splAddress
          enum:
            - splAddress
        addresses:
          type: array
          description: The Solana addresses that are compared to the list of SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array.
          items:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
            description: The Solana address that is compared to the list of SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array.
          example:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        operator:
          type: string
          description: The operator to use for the comparison. Each of the SPL token transfer recipient addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array will be on the left-hand side of the operator, and the `addresses` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - addresses
        - operator
    SplValueCriterion:
      x-audience: public
      type: object
      title: SplValueCriterion
      description: The criterion for the SPL token value of a SPL token transfer instruction in a Solana transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `splValue`.
          example: splValue
          enum:
            - splValue
        splValue:
          type: string
          description: The amount of the SPL token that the transaction instruction's `value` field should be compared to.
          example: '1000000000000000000'
        operator:
          type: string
          description: The operator to use for the comparison. The transaction instruction's `value` field will be on the left-hand side of the operator, and the `splValue` field will be on the right-hand side.
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          example: <=
      required:
        - type
        - splValue
        - operator
    MintAddressCriterion:
      x-audience: public
      type: object
      title: MintAddressCriterion
      description: The criterion for the token mint addresses of a Solana transaction's SPL token transfer instructions.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `mintAddress`.
          example: mintAddress
          enum:
            - mintAddress
        addresses:
          type: array
          description: The Solana addresses that are compared to the list of token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array.
          items:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
            description: The Solana address that is compared to the list of token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array.
          example:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        operator:
          type: string
          description: The operator to use for the comparison. Each of the token mint addresses in the transaction's `accountKeys` (for legacy transactions) or `staticAccountKeys` (for V0 transactions) array will be on the left-hand side of the operator, and the `addresses` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - addresses
        - operator
    KnownIdlType:
      type: string
      x-audience: public
      title: KnownIdlType
      description: |-
        A reference to an established Solana program. When referencing a `KnownIdlType` within a policy rule configuring an `SolDataCriterion`, criteria will decode instruction data as documented in the programs. For more information on supported programs, see the links below.
          - [SystemProgram](https://docs.rs/solana-program/latest/solana_program/system_instruction/enum.SystemInstruction.html).
          - [TokenProgram](https://docs.rs/spl-token/latest/spl_token/instruction/enum.TokenInstruction.html).
          - [AssociatedTokenProgram](https://docs.rs/spl-associated-token-account/latest/spl_associated_token_account/instruction/index.html).
      enum:
        - SystemProgram
        - TokenProgram
        - AssociatedTokenProgram
    Idl:
      x-audience: public
      type: object
      description: IDL Specification following Anchor's IDL format v0.30+.
      required:
        - address
        - instructions
      properties:
        address:
          type: string
          description: The program address.
          example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
        instructions:
          type: array
          description: List of program instructions.
          example:
            - name: transfer_checked
              discriminator:
                - 119
                - 250
                - 202
                - 24
                - 253
                - 135
                - 244
                - 121
              accounts:
                - name: mint
                  writable: true
                - name: rent
              args:
                - name: amount
                  type: u64
                - name: decimals
                  type: u8
          items:
            type: object
            required:
              - name
              - discriminator
              - args
            properties:
              name:
                type: string
                description: The instruction name.
                example: transfer_checked
              discriminator:
                type: array
                description: Array of 8 numbers representing the instruction discriminator.
                items:
                  type: integer
                  minimum: 0
                  maximum: 255
                minItems: 8
                maxItems: 8
                example:
                  - 119
                  - 250
                  - 202
                  - 24
                  - 253
                  - 135
                  - 244
                  - 121
              args:
                type: array
                description: List of instruction arguments.
                items:
                  type: object
                  required:
                    - name
                    - type
                  properties:
                    name:
                      type: string
                      description: The argument name.
                      example: amount
                    type:
                      type: string
                      description: The argument type.
                      example: u64
              accounts:
                type: array
                description: Optional list of accounts required by the instruction.
                items:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      description: The account name.
                      example: mint
                    writable:
                      type: boolean
                      description: Whether the account is writable.
                      example: true
                    signer:
                      type: boolean
                      description: Whether the account must be a signer.
                      example: false
        metadata:
          type: object
          description: Optional metadata about the IDL.
          example:
            name: system_program
            version: 0.1.0
            spec: 0.1.0
          properties:
            name:
              type: string
              description: The program name.
              example: system_program
            version:
              type: string
              description: The program version.
              example: 0.1.0
            spec:
              type: string
              description: The IDL specification version.
              example: 0.1.0
        types:
          type: array
          description: Optional type definitions for custom data structures used in the program.
          items:
            type: object
          example:
            - name: MyStruct
              type: struct
              fields:
                - name: id
                  type: u64
                - name: owner
                  type: pubkey
    SolDataParameterCondition:
      type: object
      x-audience: public
      title: SolDataParameterCondition
      description: A single parameter condition to apply against a specific instruction's parameters.
      properties:
        name:
          type: string
          description: The parameter name.
          example: amount
        operator:
          type: string
          description: The operator to use for the comparison. The value resolved at the `name` will be on the left-hand side of the operator, and the `value` field will be on the right-hand side.
          enum:
            - '>'
            - '>='
            - <
            - <=
            - '=='
          example: '=='
        value:
          type: string
          description: The value to compare against.
          example: '1000000'
      required:
        - name
        - operator
        - value
    SolDataParameterConditionList:
      type: object
      x-audience: public
      title: SolDataParameterConditionList
      description: A single parameter condition to apply against a specific instruction's parameters.
      properties:
        name:
          type: string
          description: The parameter name.
          example: amount
        operator:
          type: string
          description: The operator to use for the comparison. The value resolved at the `name` will be on the left-hand side of the operator, and the `value` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
        values:
          type: array
          description: The values to compare against.
          items:
            type: string
            description: A single potential value to compare against the resolved `name` value.
            example: '1000000'
          example:
            - '1000000'
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
            - '6'
      required:
        - name
        - operator
        - values
    SolDataCondition:
      type: object
      x-audience: public
      description: A single condition to apply against a specific instruction type and its parameters.
      properties:
        instruction:
          type: string
          description: The instruction name.
          example: transfer_checked
        params:
          type: array
          description: Parameter conditions for the instruction.
          items:
            description: A list of parameter conditions to apply against a specific instruction's data.
            oneOf:
              - $ref: '#/components/schemas/SolDataParameterCondition'
              - $ref: '#/components/schemas/SolDataParameterConditionList'
          example:
            - name: amount
              operator: <=
              value: '1000000'
            - name: decimals
              operator: '=='
              value: '6'
            - name: owner
              operator: in
              values:
                - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
                - So11111111111111111111111111111111111111112
      required:
        - instruction
    SolDataCriterion:
      x-audience: public
      type: object
      description: A schema for specifying criterion for instruction data in a Solana transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `solData`.
          example: solData
          enum:
            - solData
        idls:
          type: array
          description: List of IDL specifications. Can contain known program names (strings) or custom IDL objects.
          items:
            oneOf:
              - $ref: '#/components/schemas/KnownIdlType'
              - $ref: '#/components/schemas/Idl'
          example:
            - SystemProgram
            - TokenProgram
            - address: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
              instructions:
                - name: transfer_checked
                  discriminator:
                    - 119
                    - 250
                    - 202
                    - 24
                    - 253
                    - 135
                    - 244
                    - 121
                  args:
                    - name: amount
                      type: u64
                    - name: decimals
                      type: u8
        conditions:
          type: array
          description: A list of conditions to apply against the transaction instruction. Only one condition must evaluate to true for this criterion to be met.
          items:
            $ref: '#/components/schemas/SolDataCondition'
          example:
            - instruction: transfer_checked
              params:
                - name: lamports
                  operator: <=
                  value: '1000000'
                - name: space
                  operator: '=='
                  value: '64'
      required:
        - type
        - idls
        - conditions
    ProgramIdCriterion:
      x-audience: public
      type: object
      title: ProgramIdCriterion
      description: The criterion for the program IDs of a Solana transaction's instructions.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `programId`.
          example: programId
          enum:
            - programId
        programIds:
          type: array
          description: The Solana program IDs that are compared to the list of program IDs in the transaction's instructions.
          items:
            type: string
            pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
            description: The Solana program ID that is compared to the list of program IDs in the transaction's instructions.
          example:
            - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
            - '11111111111111111111111111111112'
        operator:
          type: string
          description: The operator to use for the comparison. Each of the program IDs in the transaction's instructions will be on the left-hand side of the operator, and the `programIds` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - programIds
        - operator
    SignSolTransactionCriteria:
      type: array
      x-audience: public
      description: A schema for specifying criteria for the SignSolTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SolAddressCriterion'
          - $ref: '#/components/schemas/SolValueCriterion'
          - $ref: '#/components/schemas/SplAddressCriterion'
          - $ref: '#/components/schemas/SplValueCriterion'
          - $ref: '#/components/schemas/MintAddressCriterion'
          - $ref: '#/components/schemas/SolDataCriterion'
          - $ref: '#/components/schemas/ProgramIdCriterion'
      example:
        - type: solAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
    SignSolTransactionRule:
      title: SignSolTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signSolTransaction
          enum:
            - signSolTransaction
        criteria:
          $ref: '#/components/schemas/SignSolTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    SolNetworkCriterion:
      x-audience: public
      type: object
      title: SolNetworkCriterion
      description: The criterion for the Solana network of a transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `solNetwork`.
          example: solNetwork
          enum:
            - solNetwork
        networks:
          type: array
          description: The Solana networks that the transaction's intended network should be compared to.
          items:
            type: string
            description: The Solana network the transaction is for.
            enum:
              - solana-devnet
              - solana
            example: solana-devnet
          example:
            - solana-devnet
            - solana
        operator:
          type: string
          description: The operator to use for the comparison. The transaction's intended network will be on the left-hand side of the operator, and the `networks` field will be on the right-hand side.
          enum:
            - in
            - not in
          example: in
      required:
        - type
        - networks
        - operator
    SendSolTransactionCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the SendSolTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SolAddressCriterion'
          - $ref: '#/components/schemas/SolValueCriterion'
          - $ref: '#/components/schemas/SplAddressCriterion'
          - $ref: '#/components/schemas/SplValueCriterion'
          - $ref: '#/components/schemas/MintAddressCriterion'
          - $ref: '#/components/schemas/SolDataCriterion'
          - $ref: '#/components/schemas/ProgramIdCriterion'
          - $ref: '#/components/schemas/SolNetworkCriterion'
      example:
        - type: solAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: solValue
          solValue: '1000000000000000000'
          operator: <=
    SendSolTransactionRule:
      x-audience: public
      title: SendSolTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendSolTransaction
          enum:
            - sendSolTransaction
        criteria:
          $ref: '#/components/schemas/SendSolTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    SolMessageCriterion:
      x-audience: public
      type: object
      title: SolMessageCriterion
      description: The criterion for the message of a Solana transaction.
      properties:
        type:
          type: string
          description: The type of criterion to use. This should be `solMessage`.
          example: solMessage
          enum:
            - solMessage
        match:
          type: string
          description: A regular expression the field is matched against.
          example: ^hello ([a-z]+)$
      required:
        - type
        - match
    SignSolMessageCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the SignSolMessage operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SolMessageCriterion'
      example:
        - type: solMessage
          match: ^hello ([a-z]+)$
    SignSolMessageRule:
      x-audience: public
      title: SignSolMessageRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signSolMessage
          enum:
            - signSolMessage
        criteria:
          $ref: '#/components/schemas/SignSolMessageCriteria'
      required:
        - action
        - operation
        - criteria
    SignEvmHashRule:
      x-audience: public
      title: SignEvmHashRule
      properties:
        action:
          type: string
          description: Whether any attempts to sign a hash will be accepted or rejected. This rule does not accept any criteria.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies.
          example: signEvmHash
          enum:
            - signEvmHash
      required:
        - action
        - operation
    PrepareUserOperationCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the PrepareUserOperation operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
    PrepareUserOperationRule:
      x-audience: public
      title: PrepareUserOperationRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: prepareUserOperation
          enum:
            - prepareUserOperation
        criteria:
          $ref: '#/components/schemas/PrepareUserOperationCriteria'
      required:
        - action
        - operation
        - criteria
    SendUserOperationCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the SendUserOperation operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
    SendUserOperationRule:
      x-audience: public
      title: SendUserOperationRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendUserOperation
          enum:
            - sendUserOperation
        criteria:
          $ref: '#/components/schemas/SendUserOperationCriteria'
      required:
        - action
        - operation
        - criteria
    SignEndUserEvmTransactionCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the signEndUserEvmTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
        - type: evmData
          abi: erc20
          conditions:
            - function: transfer
              params:
                - name: value
                  operator: <=
                  value: '10000'
        - type: netUSDChange
          changeCents: 10000
          operator: <=
    SignEndUserEvmTransactionRule:
      x-audience: public
      title: SignEndUserEvmTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEndUserEvmTransaction
          enum:
            - signEndUserEvmTransaction
        criteria:
          $ref: '#/components/schemas/SignEndUserEvmTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    SendEndUserEvmTransactionCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the sendEndUserEvmTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
        - type: evmNetwork
          networks:
            - base
            - ethereum
          operator: in
        - type: evmData
          abi: erc20
          conditions:
            - function: transfer
              params:
                - name: value
                  operator: <=
                  value: '10000'
        - type: netUSDChange
          changeCents: 10000
          operator: <=
    SendEndUserEvmTransactionRule:
      x-audience: public
      title: SendEndUserEvmTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendEndUserEvmTransaction
          enum:
            - sendEndUserEvmTransaction
        criteria:
          $ref: '#/components/schemas/SendEndUserEvmTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    SignEndUserEvmMessageCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the signEndUserEvmMessage operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EvmMessageCriterion'
      example:
        - type: evmMessage
          match: ^hello ([a-z]+)$
    SignEndUserEvmMessageRule:
      x-audience: public
      title: SignEndUserEvmMessageRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEndUserEvmMessage
          enum:
            - signEndUserEvmMessage
        criteria:
          $ref: '#/components/schemas/SignEndUserEvmMessageCriteria'
      required:
        - action
        - operation
        - criteria
    SignEndUserEvmTypedDataCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the signEndUserEvmTypedData operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SignEvmTypedDataFieldCriterion'
          - $ref: '#/components/schemas/SignEvmTypedDataVerifyingContractCriterion'
      example:
        - type: evmTypedDataField
          types:
            types:
              Person:
                - name: name
                  type: string
                - name: wallet
                  type: address
                - name: score
                  type: uint256
              Mail:
                - name: from
                  type: Person
                - name: to
                  type: Person
                - name: contents
                  type: string
            primaryType: Mail
          conditions:
            - addresses:
                - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              operator: in
              path: to.wallet
            - value: '50'
              operator: '>='
              path: to.score
            - match: ^hello ([a-z]+)$
              path: contents
        - type: evmTypedDataVerifyingContract
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
    SignEndUserEvmTypedDataRule:
      x-audience: public
      title: SignEndUserEvmTypedDataRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEndUserEvmTypedData
          enum:
            - signEndUserEvmTypedData
        criteria:
          $ref: '#/components/schemas/SignEndUserEvmTypedDataCriteria'
      required:
        - action
        - operation
        - criteria
    SignEndUserEvmHashRule:
      x-audience: public
      title: SignEndUserEvmHashRule
      properties:
        action:
          type: string
          description: Whether any attempts to sign a hash will be accepted or rejected. This rule does not accept any criteria.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies.
          example: signEndUserEvmHash
          enum:
            - signEndUserEvmHash
      required:
        - action
        - operation
    SignEndUserSolTransactionCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the signEndUserSolTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SolAddressCriterion'
          - $ref: '#/components/schemas/SolValueCriterion'
          - $ref: '#/components/schemas/SplAddressCriterion'
          - $ref: '#/components/schemas/SplValueCriterion'
          - $ref: '#/components/schemas/MintAddressCriterion'
          - $ref: '#/components/schemas/SolDataCriterion'
          - $ref: '#/components/schemas/ProgramIdCriterion'
      example:
        - type: solAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: solValue
          solValue: '1000000000000000000'
          operator: <=
        - type: splAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: splValue
          splValue: '1000000000000000000'
          operator: <=
        - type: mintAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: solData
          idls:
            - SystemProgram
          conditions:
            - instruction: transfer_checked
              params:
                - name: lamports
                  operator: <=
                  value: '1000000'
        - type: programId
          programIds:
            - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
          operator: in
    SignEndUserSolTransactionRule:
      x-audience: public
      title: SignEndUserSolTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEndUserSolTransaction
          enum:
            - signEndUserSolTransaction
        criteria:
          $ref: '#/components/schemas/SignEndUserSolTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    SendEndUserSolTransactionCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the sendEndUserSolTransaction operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SolAddressCriterion'
          - $ref: '#/components/schemas/SolValueCriterion'
          - $ref: '#/components/schemas/SplAddressCriterion'
          - $ref: '#/components/schemas/SplValueCriterion'
          - $ref: '#/components/schemas/MintAddressCriterion'
          - $ref: '#/components/schemas/SolDataCriterion'
          - $ref: '#/components/schemas/ProgramIdCriterion'
          - $ref: '#/components/schemas/SolNetworkCriterion'
      example:
        - type: solAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: solValue
          solValue: '1000000000000000000'
          operator: <=
        - type: splAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: splValue
          splValue: '1000000000000000000'
          operator: <=
        - type: mintAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: solData
          idls:
            - SystemProgram
          conditions:
            - instruction: transfer_checked
              params:
                - name: lamports
                  operator: <=
                  value: '1000000'
        - type: programId
          programIds:
            - TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
          operator: in
        - type: solNetwork
          networks:
            - solana-devnet
            - solana
          operator: in
    SendEndUserSolTransactionRule:
      x-audience: public
      title: SendEndUserSolTransactionRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendEndUserSolTransaction
          enum:
            - sendEndUserSolTransaction
        criteria:
          $ref: '#/components/schemas/SendEndUserSolTransactionCriteria'
      required:
        - action
        - operation
        - criteria
    SignEndUserSolMessageCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the signEndUserSolMessage operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SolMessageCriterion'
      example:
        - type: solMessage
          match: ^hello ([a-z]+)$
    SignEndUserSolMessageRule:
      x-audience: public
      title: SignEndUserSolMessageRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: signEndUserSolMessage
          enum:
            - signEndUserSolMessage
        criteria:
          $ref: '#/components/schemas/SignEndUserSolMessageCriteria'
      required:
        - action
        - operation
        - criteria
    SendEndUserEvmAssetCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the sendEndUserEvmAsset operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
        - type: evmNetwork
          networks:
            - base
            - ethereum
          operator: in
        - type: evmData
          abi: erc20
          conditions:
            - function: transfer
              params:
                - name: value
                  operator: <=
                  value: '10000'
        - type: netUSDChange
          changeCents: 10000
          operator: <=
    SendEndUserEvmAssetRule:
      x-audience: public
      title: SendEndUserEvmAssetRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendEndUserEvmAsset
          enum:
            - sendEndUserEvmAsset
        criteria:
          $ref: '#/components/schemas/SendEndUserEvmAssetCriteria'
      required:
        - action
        - operation
        - criteria
    SendEndUserSolAssetCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the sendEndUserSolAsset operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/SplAddressCriterion'
          - $ref: '#/components/schemas/SplValueCriterion'
          - $ref: '#/components/schemas/SolDataCriterion'
          - $ref: '#/components/schemas/SolNetworkCriterion'
      example:
        - type: splAddress
          addresses:
            - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
          operator: in
        - type: splValue
          splValue: '1000000000000000000'
          operator: <=
        - type: solData
          idls:
            - SystemProgram
          conditions:
            - instruction: transfer_checked
              params:
                - name: lamports
                  operator: <=
                  value: '1000000'
        - type: solNetwork
          networks:
            - solana-devnet
            - solana
          operator: in
    SendEndUserSolAssetRule:
      x-audience: public
      title: SendEndUserSolAssetRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendEndUserSolAsset
          enum:
            - sendEndUserSolAsset
        criteria:
          $ref: '#/components/schemas/SendEndUserSolAssetCriteria'
      required:
        - action
        - operation
        - criteria
    SendEndUserOperationCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the sendEndUserOperation operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EthValueCriterion'
          - $ref: '#/components/schemas/EvmAddressCriterion'
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: ethValue
          ethValue: '1000000'
          operator: '>='
        - type: evmAddress
          addresses:
            - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          operator: in
        - type: evmNetwork
          networks:
            - base
            - ethereum
          operator: in
        - type: evmData
          abi: erc20
          conditions:
            - function: transfer
              params:
                - name: value
                  operator: <=
                  value: '10000'
        - type: netUSDChange
          changeCents: 10000
          operator: <=
    SendEndUserOperationRule:
      x-audience: public
      title: SendEndUserOperationRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: sendEndUserOperation
          enum:
            - sendEndUserOperation
        criteria:
          $ref: '#/components/schemas/SendEndUserOperationCriteria'
      required:
        - action
        - operation
        - criteria
    CreateEndUserEvmSwapCriteria:
      x-audience: public
      type: array
      description: A schema for specifying criteria for the createEndUserEvmSwap operation.
      items:
        oneOf:
          - $ref: '#/components/schemas/EvmNetworkCriterion'
          - $ref: '#/components/schemas/EvmDataCriterion'
          - $ref: '#/components/schemas/NetUSDChangeCriterion'
      example:
        - type: evmNetwork
          networks:
            - base
            - ethereum
          operator: in
        - type: evmData
          abi: erc20
          conditions:
            - function: transfer
              params:
                - name: value
                  operator: <=
                  value: '10000'
        - type: netUSDChange
          changeCents: 10000
          operator: <=
    CreateEndUserEvmSwapRule:
      x-audience: public
      title: CreateEndUserEvmSwapRule
      properties:
        action:
          type: string
          description: Whether matching the rule will cause the request to be rejected or accepted.
          example: accept
          enum:
            - reject
            - accept
        operation:
          type: string
          description: The operation to which the rule applies. Every element of the `criteria` array must match the specified operation.
          example: createEndUserEvmSwap
          enum:
            - createEndUserEvmSwap
        criteria:
          $ref: '#/components/schemas/CreateEndUserEvmSwapCriteria'
      required:
        - action
        - operation
        - criteria
    Rule:
      type: object
      description: A rule that limits the behavior of an account.
      oneOf:
        - $ref: '#/components/schemas/SignEvmTransactionRule'
        - $ref: '#/components/schemas/SendEvmTransactionRule'
        - $ref: '#/components/schemas/SignEvmMessageRule'
        - $ref: '#/components/schemas/SignEvmTypedDataRule'
        - $ref: '#/components/schemas/SignSolTransactionRule'
        - $ref: '#/components/schemas/SendSolTransactionRule'
        - $ref: '#/components/schemas/SignSolMessageRule'
        - $ref: '#/components/schemas/SignEvmHashRule'
        - $ref: '#/components/schemas/PrepareUserOperationRule'
        - $ref: '#/components/schemas/SendUserOperationRule'
        - $ref: '#/components/schemas/SignEndUserEvmTransactionRule'
        - $ref: '#/components/schemas/SendEndUserEvmTransactionRule'
        - $ref: '#/components/schemas/SignEndUserEvmMessageRule'
        - $ref: '#/components/schemas/SignEndUserEvmTypedDataRule'
        - $ref: '#/components/schemas/SignEndUserEvmHashRule'
        - $ref: '#/components/schemas/SignEndUserSolTransactionRule'
        - $ref: '#/components/schemas/SendEndUserSolTransactionRule'
        - $ref: '#/components/schemas/SignEndUserSolMessageRule'
        - $ref: '#/components/schemas/SendEndUserEvmAssetRule'
        - $ref: '#/components/schemas/SendEndUserSolAssetRule'
        - $ref: '#/components/schemas/SendEndUserOperationRule'
        - $ref: '#/components/schemas/CreateEndUserEvmSwapRule'
      example:
        action: accept
        operation: signEvmTransaction
        criteria:
          - type: ethValue
            ethValue: '1000000'
            operator: '>='
          - type: evmAddress
            addresses:
              - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
            operator: in
    Policy:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the policy.
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 123e4567-e89b-12d3-a456-426614174000
        description:
          type: string
          description: |-
            An optional human-readable description of the policy.
            Policy descriptions can consist of alphanumeric characters, spaces, commas, and periods, and be 50 characters or less.
          pattern: ^[A-Za-z0-9 ,.]{1,50}$
          example: Default policy
        scope:
          type: string
          description: The scope of the policy. Only one project-level policy can exist at any time.
          enum:
            - project
            - account
          example: project
        rules:
          type: array
          description: A list of rules that comprise the policy.
          items:
            $ref: '#/components/schemas/Rule'
          example:
            - action: accept
              operation: signEvmTransaction
              criteria:
                - type: ethValue
                  ethValue: '1000000000000000000'
                  operator: <=
                - type: evmAddress
                  addresses:
                    - '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                    - '0x1234567890123456789012345678901234567890'
                  operator: in
            - action: accept
              operation: signSolTransaction
              criteria:
                - type: solAddress
                  addresses:
                    - HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
                  operator: in
        createdAt:
          type: string
          description: The ISO 8601 timestamp at which the Policy was created.
          example: '2025-03-25T12:00:00Z'
        updatedAt:
          type: string
          description: The ISO 8601 timestamp at which the Policy was last updated.
          example: '2025-03-26T12:00:00Z'
      required:
        - id
        - scope
        - rules
        - createdAt
        - updatedAt
    SolanaAccount:
      type: object
      properties:
        address:
          type: string
          pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          description: The base58 encoded Solana address.
          example: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
        name:
          type: string
          description: |-
            An optional name for the account.
            Account names can consist of alphanumeric characters and hyphens, and be between 2 and 36 characters long.
            Account names are guaranteed to be unique across all Solana accounts in the developer's CDP Project.
          example: my-account
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,34}[A-Za-z0-9]$
        policies:
          type: array
          x-audience: public
          description: The list of policy IDs that apply to the account. This will include both the project-level policy and the account-level policy, if one exists.
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example:
            - 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          description: The ISO 8601 UTC timestamp at which the account was created.
          example: '2025-03-25T12:00:00Z'
          format: date-time
        updatedAt:
          type: string
          description: The ISO 8601 UTC timestamp at which the account was last updated.
          example: '2025-03-26T12:00:00Z'
          format: date-time
      required:
        - address
    ListSolanaTokenBalancesNetwork:
      type: string
      enum:
        - solana
        - solana-devnet
      description: The name of the supported Solana networks in human-readable format.
      example: solana
    SolanaTokenAmount:
      type: object
      description: Amount of a given Solana token.
      example:
        amount: '1250000000'
        decimals: 9
      properties:
        amount:
          type: string
          pattern: ^[0-9]+$
          description: The amount is denominated in the smallest indivisible unit of the token. For SOL, the smallest indivisible unit is lamports (10^-9 SOL). For SPL tokens, the smallest unit is defined by the token's decimals configuration.
          example: '1250000000'
        decimals:
          type: integer
          format: int64
          description: |-
            'decimals' is the exponential value N that satisfies the equation `amount * 10^-N = standard_denomination`. The standard denomination is the most commonly used denomination for the token.
            - For native SOL, `decimals` is 9 (1 SOL = 10^9 lamports). - For SPL tokens, `decimals` is defined in the token's mint configuration.
          example: 9
      required:
        - amount
        - decimals
    SolanaToken:
      type: object
      description: General information about a Solana token. Includes the mint address, and other identifying information.
      example:
        symbol: SOL
        name: Solana
        mintAddress: So11111111111111111111111111111111111111111
      properties:
        symbol:
          type: string
          description: |-
            The symbol of this token (ex: SOL, USDC, RAY).
            The token symbol is not unique. It is possible for two different tokens to have the same symbol.
            For the native SOL token, this symbol is "SOL". For SPL tokens, this symbol is defined in the token's metadata.
            Not all tokens have a symbol. This field will only be populated when the token has metadata available.
          example: SOL
        name:
          type: string
          description: |-
            The name of this token (ex: "Solana", "USD Coin", "Raydium").
            The token name is not unique. It is possible for two different tokens to have the same name.
            For the native SOL token, this name is "Solana". For SPL tokens, this name is defined in the token's metadata.
            Not all tokens have a name. This field will only be populated when the token has metadata available.
          example: Solana
        mintAddress:
          type: string
          pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          description: |-
            The mint address of the token.
            For native SOL, the mint address is `So11111111111111111111111111111111111111111`. For SPL tokens, this is the mint address where the token is defined.
          example: So11111111111111111111111111111111111111111
      required:
        - mintAddress
    SolanaTokenBalance:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/SolanaTokenAmount'
        token:
          $ref: '#/components/schemas/SolanaToken'
      required:
        - amount
        - token
    OnchainDataQuery:
      type: object
      description: Request to execute a SQL query against indexed blockchain data.
      required:
        - sql
      properties:
        sql:
          type: string
          description: SQL query to execute against the indexed blockchain data.
          example: SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10
          minLength: 1
          maxLength: 100000
        cache:
          type: object
          title: Query result cache configuration
          description: |
            Enables control over how often queries need to be fully re-executed on the backing store.
            This can be useful in scenarios where API calls might be made frequently, API latency is critical, and some freshness lag (ex: 750ms, 2s, 5s) is tolerable.
            By default, each query result is returned from cache so long as the result is from an identical query and less than 500ms old. This freshness tolerance can be modified upwards, to a maximum of 900000ms (i.e. 900s, 15m).
          example:
            maxAgeMs: 1000
          properties:
            maxAgeMs:
              type: integer
              description: The maximum tolerable staleness of the query result cache in milliseconds. If a previous execution result of an identical query is older than this age, the query will be re-executed. If the data is less than this age, the result will be returned from cache.
              example: 1000
              default: 500
              minimum: 500
              maximum: 900000
    OnchainDataResult:
      type: object
      description: Result of executing a SQL query.
      properties:
        result:
          type: array
          description: Query result as an array of objects representing rows.
          items:
            type: object
            additionalProperties: true
            description: Row data with column names as keys.
            example:
              event_signature: Transfer(address,address,uint256)
              from: '0x1234567890abcdef'
              to: '0x1234567890abcdef'
              amount: 1000000000000000000
          example:
            - event_signature: Transfer(address,address,uint256)
              from: '0x1234567890abcdef'
              to: '0x1234567890abcdef'
              amount: 1000000000000000000
            - event_signature: Transfer(address,address,uint256)
              from: '0x1234567890abcdef'
              to: '0x1234567890abcdef'
              amount: 2000000000000000000
        schema:
          type: object
          description: |
            Schema information for the query result. This is a derived schema from the query result, so types may not match the underlying table.
          example:
            columns:
              - name: block_number
                type: UInt64
              - name: transaction_hash
                type: String
          properties:
            columns:
              type: array
              description: Column definitions.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Column name.
                  type:
                    type: string
                    description: Column data type (ClickHouse types).
                    enum:
                      - String
                      - UInt8
                      - UInt16
                      - UInt32
                      - UInt64
                      - UInt128
                      - UInt256
                      - Int8
                      - Int16
                      - Int32
                      - Int64
                      - Int128
                      - Int256
                      - Float32
                      - Float64
                      - Bool
                      - Date
                      - DateTime
                      - DateTime64
                      - UUID
                example:
                  name: event_signature
                  type: String
                  description: The signature of the event.
        metadata:
          type: object
          description: Metadata about query execution.
          properties:
            cached:
              type: boolean
              description: Whether the result was served from the query result cache.
              example: false
            executionTimestamp:
              type: string
              description: When the query result was executed against the backing store in RFC 3339 format.
              format: date-time
              example: '2025-01-01T00:00:00.000Z'
            executionTimeMs:
              type: integer
              description: Query execution time in milliseconds.
              example: 145
            rowCount:
              type: integer
              description: Number of rows returned.
              example: 2
          example:
            cached: false
            executionTimestamp: '2025-01-01T00:00:00.000Z'
            executionTimeMs: 145
            rowCount: 2
    OnchainDataColumnSchema:
      type: object
      description: Schema definition for a table column.
      properties:
        name:
          type: string
          description: Column name.
          example: event_signature
        type:
          type: string
          description: Column data type.
          example: String
        nullable:
          type: boolean
          description: Whether this column can contain NULL values.
          example: false
        description:
          allOf:
            - $ref: '#/components/schemas/Description'
          description: Human-readable description of the column.
          example: The signature of the decoded event log.
        indexOrder:
          type: integer
          description: The order of the column in the index. A lower number means the column is more important for the index and should be first in the query.
          example: 0
      example:
        name: event_signature
        type: String
        nullable: false
        description: The signature of the decoded event log.
        indexOrder: 0
    OnchainDataTableSchema:
      type: object
      description: Schema definition for a data table.
      properties:
        database:
          type: string
          description: The blockchain network database this table belongs to.
          example: base
        table:
          type: string
          description: Table name.
          example: events
        columns:
          type: array
          description: Column definitions for this table.
          items:
            $ref: '#/components/schemas/OnchainDataColumnSchema'
          example:
            - name: event_signature
              type: String
              nullable: false
              description: The signature of the decoded event log.
              indexOrder: 0
      example:
        database: base
        table: events
        columns:
          - name: event_signature
            type: String
            nullable: false
            description: The signature of the decoded event log.
            indexOrder: 0
          - name: address
            type: String
            nullable: false
            description: The address of the smart contract that emitted the event log.
            indexOrder: 1
    OnchainDataSchemaResponse:
      type: object
      description: Schema information for available blockchain data tables.
      properties:
        tables:
          type: array
          description: List of available tables.
          items:
            $ref: '#/components/schemas/OnchainDataTableSchema'
          example:
            - database: base
              table: events
              columns:
                - name: event_signature
                  type: String
                  nullable: false
                  description: The signature of the decoded event log.
                  indexOrder: 0
    AccountTokenAddressesResponse:
      type: object
      description: Response containing token addresses that an account has received.
      properties:
        accountAddress:
          type: string
          description: The account address that was queried.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        tokenAddresses:
          type: array
          description: List of token contract addresses that the account has received.
          items:
            type: string
            pattern: ^0x[0-9a-fA-F]{40}$
            description: Token contract address.
          example:
            - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            - '0x4200000000000000000000000000000000000006'
            - '0x0000000000000000000000000000000000000000'
        totalCount:
          type: integer
          description: Total number of unique token addresses discovered.
          example: 15
          minimum: 0
    WebhookDescription:
      type: string
      minLength: 0
      maxLength: 100
      description: |
        A human-readable description of the webhook subscription.
        Must be at most 100 characters.
      example: Subscription for token transfer events
    EventType:
      type: string
      description: |
        A webhook event type identifier following dot-separated format:
        `<domain>.<entity>.<verb>` (e.g., "onchain.activity.detected").
      example: onchain.activity.detected
      enum:
        - onchain.activity.detected
        - wallet.activity.detected
        - wallet.activity.multi
        - wallet.transaction.created
        - wallet.transaction.signed
        - wallet.transaction.broadcast
        - wallet.transaction.replaced
        - wallet.transaction.pending
        - wallet.transaction.confirmed
        - wallet.transaction.failed
        - wallet.delegation.created
        - wallet.delegation.revoked
        - wallet.typed_data.signed
        - wallet.message.signed
        - wallet.hash.signed
        - payments.transfers.quoted
        - payments.transfers.processing
        - payments.transfers.completed
        - payments.transfers.failed
        - payments.transfers.expired
        - payments.transfers.travel_rule_incomplete
        - payments.transfers.travel_rule_completed
        - onramp.transaction.created
        - onramp.transaction.updated
        - onramp.transaction.success
        - onramp.transaction.failed
        - offramp.transaction.created
        - offramp.transaction.updated
        - offramp.transaction.success
        - offramp.transaction.failed
        - acceptance.payment_session.created
        - acceptance.payment_session.canceled
        - acceptance.payment_session.authorization_pending
        - acceptance.payment_session.authorization_succeeded
        - acceptance.payment_session.authorization_failed
        - acceptance.payment_session.capture_pending
        - acceptance.payment_session.capture_succeeded
        - acceptance.payment_session.capture_failed
        - acceptance.payment_session.refund_pending
        - acceptance.payment_session.refund_succeeded
        - acceptance.payment_session.refund_failed
        - acceptance.payment_session.void_pending
        - acceptance.payment_session.void_succeeded
        - acceptance.payment_session.void_failed
        - acceptance.disbursement.pending
        - acceptance.disbursement.succeeded
        - acceptance.disbursement.failed
        - customers.capability.changed
        - customers.customer.deleted
    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:
          $ref: '#/components/schemas/WebhookDescription'
        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:
          $ref: '#/components/schemas/WebhookDescription'
        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:
          $ref: '#/components/schemas/WebhookDescription'
        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
    x402VerifyInvalidReason:
      type: string
      description: The reason the payment is invalid on the x402 protocol.
      enum:
        - insufficient_funds
        - invalid_scheme
        - invalid_network
        - invalid_x402_version
        - invalid_payment_requirements
        - invalid_payload
        - invalid_exact_evm_payload_authorization_value
        - invalid_exact_evm_payload_authorization_value_too_low
        - invalid_exact_evm_payload_authorization_valid_after
        - invalid_exact_evm_payload_authorization_valid_before
        - invalid_exact_evm_payload_authorization_typed_data_message
        - invalid_exact_evm_payload_authorization_from_address_kyt
        - invalid_exact_evm_payload_authorization_to_address_kyt
        - invalid_exact_evm_payload_signature
        - invalid_exact_evm_payload_signature_address
        - invalid_exact_evm_permit2_payload_allowance_required
        - invalid_exact_evm_permit2_payload_signature
        - invalid_exact_evm_permit2_payload_deadline
        - invalid_exact_evm_permit2_payload_valid_after
        - invalid_exact_evm_permit2_payload_spender
        - invalid_exact_evm_permit2_payload_recipient
        - invalid_exact_evm_permit2_payload_amount
        - invalid_exact_svm_payload_transaction
        - invalid_exact_svm_payload_transaction_amount_mismatch
        - invalid_exact_svm_payload_transaction_create_ata_instruction
        - invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee
        - invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset
        - invalid_exact_svm_payload_transaction_instructions
        - invalid_exact_svm_payload_transaction_instructions_length
        - invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction
        - invalid_exact_svm_payload_transaction_instructions_compute_price_instruction
        - invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high
        - invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked
        - invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked
        - invalid_exact_svm_payload_transaction_not_a_transfer_instruction
        - invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata
        - invalid_exact_svm_payload_transaction_receiver_ata_not_found
        - invalid_exact_svm_payload_transaction_sender_ata_not_found
        - invalid_exact_svm_payload_transaction_simulation_failed
        - invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata
        - invalid_exact_svm_payload_transaction_fee_payer_included_in_instruction_accounts
        - invalid_exact_svm_payload_transaction_fee_payer_transferring_funds
        - invalid_batch_settlement_evm_scheme
        - invalid_batch_settlement_evm_network_mismatch
        - invalid_batch_settlement_evm_payload_type
        - invalid_batch_settlement_evm_channel_not_found
        - invalid_batch_settlement_evm_deposit_simulation_failed
        - invalid_batch_settlement_evm_channel_id_mismatch
        - invalid_batch_settlement_evm_channel_state_read_failed
        - invalid_batch_settlement_evm_cumulative_below_claimed
        - invalid_batch_settlement_evm_cumulative_exceeds_balance
        - invalid_batch_settlement_evm_eip2612_amount_mismatch
        - invalid_batch_settlement_evm_eip2612_asset_mismatch
        - invalid_batch_settlement_evm_eip2612_deadline_expired
        - invalid_batch_settlement_evm_eip2612_invalid_format
        - invalid_batch_settlement_evm_eip2612_invalid_signature
        - invalid_batch_settlement_evm_eip2612_owner_mismatch
        - invalid_batch_settlement_evm_eip2612_spender_mismatch
        - invalid_batch_settlement_evm_erc20_approval_asset_mismatch
        - invalid_batch_settlement_evm_erc20_approval_from_mismatch
        - invalid_batch_settlement_evm_erc20_approval_invalid_format
        - invalid_batch_settlement_evm_erc20_approval_unavailable
        - invalid_batch_settlement_evm_erc20_approval_wrong_spender
        - invalid_batch_settlement_evm_erc3009_authorization_required
        - invalid_batch_settlement_evm_insufficient_balance
        - invalid_batch_settlement_evm_deposit_payload
        - invalid_batch_settlement_evm_receive_authorization_signature
        - invalid_batch_settlement_evm_refund_payload
        - invalid_batch_settlement_evm_voucher_payload
        - invalid_batch_settlement_evm_voucher_signature
        - invalid_batch_settlement_evm_missing_eip712_domain
        - invalid_batch_settlement_evm_payload_authorization_valid_after
        - invalid_batch_settlement_evm_payload_authorization_valid_before
        - invalid_batch_settlement_evm_permit2_allowance_required
        - invalid_batch_settlement_evm_permit2_amount_mismatch
        - invalid_batch_settlement_evm_permit2_authorization_required
        - invalid_batch_settlement_evm_permit2_deadline_expired
        - invalid_batch_settlement_evm_permit2_invalid_signature
        - invalid_batch_settlement_evm_permit2_invalid_spender
        - invalid_batch_settlement_evm_receiver_authorizer_mismatch
        - invalid_batch_settlement_evm_receiver_mismatch
        - invalid_batch_settlement_evm_rpc_read_failed
        - invalid_batch_settlement_evm_token_mismatch
        - invalid_batch_settlement_evm_withdraw_delay_mismatch
        - invalid_batch_settlement_evm_withdraw_delay_out_of_range
        - invalid_exact_evm_scheme
        - invalid_exact_evm_network_mismatch
        - invalid_exact_evm_payload
        - invalid_exact_evm_payload_missing_signature
        - invalid_exact_evm_failed_to_get_network_config
        - invalid_exact_evm_missing_eip712_domain
        - invalid_exact_evm_recipient_mismatch
        - invalid_exact_evm_authorization_value
        - invalid_exact_evm_required_amount
        - invalid_exact_evm_payload_authorization_value_mismatch
        - invalid_exact_evm_failed_to_check_nonce
        - invalid_exact_evm_nonce_already_used
        - invalid_exact_evm_failed_to_get_balance
        - invalid_exact_evm_insufficient_balance
        - invalid_exact_evm_signature_format
        - invalid_exact_evm_failed_to_verify_signature
        - invalid_exact_evm_signature
        - invalid_exact_evm_token_name_mismatch
        - invalid_exact_evm_token_version_mismatch
        - invalid_exact_evm_eip3009_not_supported
        - invalid_exact_evm_transaction_simulation_failed
        - invalid_exact_evm_verification_failed
        - invalid_exact_evm_failed_to_parse_signature
        - invalid_exact_evm_failed_to_check_deployment
        - invalid_exact_evm_failed_to_execute_transfer
        - invalid_exact_evm_failed_to_get_receipt
        - invalid_exact_evm_transaction_failed
        - invalid_exact_evm_payload_undeployed_smart_wallet
        - smart_wallet_deployment_failed
        - unsupported_payload_type
        - invalid_erc20_approval_extension_format
        - erc20_approval_tx_failed
        - erc20_approval_from_mismatch
        - erc20_approval_asset_mismatch
        - erc20_approval_spender_not_permit2
        - erc20_approval_tx_parse_failed
        - erc20_approval_tx_wrong_target
        - erc20_approval_tx_wrong_selector
        - erc20_approval_tx_wrong_spender
        - erc20_approval_tx_signer_mismatch
        - erc20_approval_tx_invalid_signature
        - invalid_exact_evm_unsupported_scheme
        - invalid_exact_evm_extra_field
        - invalid_exact_evm_payload_recipient_mismatch
        - invalid_exact_evm_insufficient_funds
        - invalid_exact_evm_transaction_state
        - invalid_permit2_spender
        - invalid_permit2_recipient_mismatch
        - permit2_deadline_expired
        - permit2_not_yet_valid
        - permit2_amount_mismatch
        - permit2_token_mismatch
        - invalid_permit2_signature
        - permit2_allowance_required
        - permit2_invalid_amount
        - permit2_invalid_destination
        - permit2_invalid_owner
        - permit2_payment_too_early
        - permit2_invalid_nonce
        - permit2_2612_amount_mismatch
        - permit2_simulation_failed
        - permit2_insufficient_balance
        - permit2_proxy_not_deployed
        - erc20_approval_insufficient_eth_for_gas
        - erc20_approval_broadcast_failed
        - invalid_exact_solana_unsupported_scheme
        - invalid_exact_solana_network_mismatch
        - invalid_exact_solana_payload_missing_fee_payer
        - invalid_exact_solana_fee_payer_not_managed_by_facilitator
        - invalid_exact_solana_payload_transaction
        - invalid_exact_solana_payload_transaction_could_not_be_decoded
        - invalid_exact_solana_payload_transaction_instructions_length
        - invalid_exact_solana_payload_unknown_fourth_instruction
        - invalid_exact_solana_payload_unknown_fifth_instruction
        - invalid_exact_solana_payload_unknown_sixth_instruction
        - invalid_exact_solana_payload_transaction_instructions_compute_limit_instruction
        - invalid_exact_solana_payload_transaction_instructions_compute_price_instruction
        - invalid_exact_solana_payload_transaction_instructions_compute_price_instruction_too_high
        - invalid_exact_solana_payload_no_transfer_instruction
        - invalid_exact_solana_payload_transaction_fee_payer_transferring_funds
        - invalid_exact_solana_payload_mint_mismatch
        - invalid_exact_solana_payload_recipient_mismatch
        - invalid_exact_solana_payload_amount_insufficient
        - invalid_exact_solana_invalid_fee_payer
        - invalid_exact_solana_transaction_signing_failed
        - invalid_exact_solana_transaction_simulation_failed
        - invalid_exact_solana_payload_memo_mismatch
        - invalid_exact_solana_payload_memo_count
        - invalid_exact_solana_verification_failed
        - invalid_exact_solana_fee_payer_mismatch
        - invalid_exact_solana_transaction_failed
        - invalid_exact_solana_transaction_confirmation_failed
        - duplicate_settlement
        - invalid_exact_solana_extra_field
        - batch_settlement_cumulative_amount_mismatch
        - batch_settlement_channel_busy
        - missing_batch_settlement_channel
        - batch_settlement_charge_exceeds_signed_cumulative
        - batch_settlement_refund_no_balance
        - batch_settlement_refund_amount_invalid
        - batch_settlement_refund_amount_exceeds_balance
        - amount_too_low
        - invalid_amount
        - kyt_risk_detected
        - permit2_disabled
        - preflight_validation_failed
        - request_blocked_by_location
        - self_send_not_allowed
        - invalid_bazaar_extension
        - unknown_error
      example: insufficient_funds
    x402VerifyPaymentRejection:
      type: object
      description: The result when x402 payment verification fails.
      properties:
        isValid:
          type: boolean
          description: Indicates whether the payment is valid.
          example: false
        invalidReason:
          $ref: '#/components/schemas/x402VerifyInvalidReason'
        invalidMessage:
          type: string
          description: The message describing the invalid reason.
          example: Insufficient funds
        payer:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: |-
            The onchain address of the client that is paying for the resource.

            For EVM networks, the payer will be a 0x-prefixed, checksum EVM address.

            For Solana-based networks, the payer will be a base58-encoded Solana address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
      required:
        - isValid
        - invalidReason
      example:
        isValid: false
        invalidReason: insufficient_funds
        invalidMessage: Insufficient funds
        payer: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    x402SettleErrorReason:
      type: string
      description: The reason the payment settlement errored on the x402 protocol.
      enum:
        - insufficient_funds
        - invalid_scheme
        - invalid_network
        - invalid_x402_version
        - invalid_payment_requirements
        - invalid_payload
        - invalid_exact_evm_payload_authorization_value
        - invalid_exact_evm_payload_authorization_value_too_low
        - invalid_exact_evm_payload_authorization_valid_after
        - invalid_exact_evm_payload_authorization_valid_before
        - invalid_exact_evm_payload_authorization_typed_data_message
        - invalid_exact_evm_payload_authorization_from_address_kyt
        - invalid_exact_evm_payload_authorization_to_address_kyt
        - invalid_exact_evm_payload_signature
        - invalid_exact_evm_payload_signature_address
        - invalid_exact_evm_permit2_payload_allowance_required
        - invalid_exact_evm_permit2_payload_signature
        - invalid_exact_evm_permit2_payload_deadline
        - invalid_exact_evm_permit2_payload_valid_after
        - invalid_exact_evm_permit2_payload_spender
        - invalid_exact_evm_permit2_payload_recipient
        - invalid_exact_evm_permit2_payload_amount
        - invalid_exact_svm_payload_transaction
        - invalid_exact_svm_payload_transaction_amount_mismatch
        - invalid_exact_svm_payload_transaction_create_ata_instruction
        - invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee
        - invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset
        - invalid_exact_svm_payload_transaction_instructions
        - invalid_exact_svm_payload_transaction_instructions_length
        - invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction
        - invalid_exact_svm_payload_transaction_instructions_compute_price_instruction
        - invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high
        - invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked
        - invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked
        - invalid_exact_svm_payload_transaction_not_a_transfer_instruction
        - invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata
        - invalid_exact_svm_payload_transaction_receiver_ata_not_found
        - invalid_exact_svm_payload_transaction_sender_ata_not_found
        - invalid_exact_svm_payload_transaction_simulation_failed
        - invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata
        - invalid_exact_svm_payload_transaction_fee_payer_included_in_instruction_accounts
        - invalid_exact_svm_payload_transaction_fee_payer_transferring_funds
        - settle_exact_evm_transaction_confirmation_timed_out
        - settle_exact_node_failure
        - settle_exact_failed_onchain
        - settle_exact_svm_block_height_exceeded
        - settle_exact_svm_transaction_confirmation_timed_out
        - settlement_pending
        - invalid_batch_settlement_evm_unknown_settle_action
        - invalid_batch_settlement_evm_claim_payload
        - invalid_batch_settlement_evm_settle_payload
        - invalid_batch_settlement_evm_authorizer_address_mismatch
        - invalid_batch_settlement_evm_claim_simulation_failed
        - invalid_batch_settlement_evm_claim_transaction_failed
        - invalid_batch_settlement_evm_deposit_transaction_failed
        - invalid_batch_settlement_evm_refund_simulation_failed
        - invalid_batch_settlement_evm_refund_transaction_failed
        - invalid_batch_settlement_evm_settle_simulation_failed
        - invalid_batch_settlement_evm_settle_transaction_failed
        - invalid_batch_settlement_evm_transaction_reverted
        - invalid_batch_settlement_evm_wait_for_receipt_failed
        - invalid_batch_settlement_evm_erc20_approval_broadcast_failed
        - invalid_batch_settlement_evm_channel_id_mismatch
        - invalid_batch_settlement_evm_channel_state_read_failed
        - invalid_batch_settlement_evm_cumulative_below_claimed
        - invalid_batch_settlement_evm_cumulative_exceeds_balance
        - invalid_batch_settlement_evm_eip2612_amount_mismatch
        - invalid_batch_settlement_evm_eip2612_asset_mismatch
        - invalid_batch_settlement_evm_eip2612_deadline_expired
        - invalid_batch_settlement_evm_eip2612_invalid_format
        - invalid_batch_settlement_evm_eip2612_invalid_signature
        - invalid_batch_settlement_evm_eip2612_owner_mismatch
        - invalid_batch_settlement_evm_eip2612_spender_mismatch
        - invalid_batch_settlement_evm_erc20_approval_asset_mismatch
        - invalid_batch_settlement_evm_erc20_approval_from_mismatch
        - invalid_batch_settlement_evm_erc20_approval_invalid_format
        - invalid_batch_settlement_evm_erc20_approval_unavailable
        - invalid_batch_settlement_evm_erc20_approval_wrong_spender
        - invalid_batch_settlement_evm_erc3009_authorization_required
        - invalid_batch_settlement_evm_insufficient_balance
        - invalid_batch_settlement_evm_deposit_payload
        - invalid_batch_settlement_evm_receive_authorization_signature
        - invalid_batch_settlement_evm_refund_payload
        - invalid_batch_settlement_evm_voucher_payload
        - invalid_batch_settlement_evm_voucher_signature
        - invalid_batch_settlement_evm_missing_eip712_domain
        - invalid_batch_settlement_evm_payload_authorization_valid_after
        - invalid_batch_settlement_evm_payload_authorization_valid_before
        - invalid_batch_settlement_evm_permit2_allowance_required
        - invalid_batch_settlement_evm_permit2_amount_mismatch
        - invalid_batch_settlement_evm_permit2_authorization_required
        - invalid_batch_settlement_evm_permit2_deadline_expired
        - invalid_batch_settlement_evm_permit2_invalid_signature
        - invalid_batch_settlement_evm_permit2_invalid_spender
        - invalid_batch_settlement_evm_receiver_authorizer_mismatch
        - invalid_batch_settlement_evm_receiver_mismatch
        - invalid_batch_settlement_evm_rpc_read_failed
        - invalid_batch_settlement_evm_token_mismatch
        - invalid_batch_settlement_evm_withdraw_delay_mismatch
        - invalid_batch_settlement_evm_withdraw_delay_out_of_range
        - invalid_batch_settlement_evm_scheme
        - invalid_batch_settlement_evm_network_mismatch
        - invalid_batch_settlement_evm_payload_type
        - invalid_batch_settlement_evm_channel_not_found
        - invalid_batch_settlement_evm_deposit_simulation_failed
        - invalid_exact_evm_scheme
        - invalid_exact_evm_network_mismatch
        - invalid_exact_evm_payload
        - invalid_exact_evm_payload_missing_signature
        - invalid_exact_evm_failed_to_get_network_config
        - invalid_exact_evm_missing_eip712_domain
        - invalid_exact_evm_recipient_mismatch
        - invalid_exact_evm_authorization_value
        - invalid_exact_evm_required_amount
        - invalid_exact_evm_payload_authorization_value_mismatch
        - invalid_exact_evm_failed_to_check_nonce
        - invalid_exact_evm_nonce_already_used
        - invalid_exact_evm_failed_to_get_balance
        - invalid_exact_evm_insufficient_balance
        - invalid_exact_evm_signature_format
        - invalid_exact_evm_failed_to_verify_signature
        - invalid_exact_evm_signature
        - invalid_exact_evm_token_name_mismatch
        - invalid_exact_evm_token_version_mismatch
        - invalid_exact_evm_eip3009_not_supported
        - invalid_exact_evm_transaction_simulation_failed
        - invalid_exact_evm_verification_failed
        - invalid_exact_evm_failed_to_parse_signature
        - invalid_exact_evm_failed_to_check_deployment
        - invalid_exact_evm_failed_to_execute_transfer
        - invalid_exact_evm_failed_to_get_receipt
        - invalid_exact_evm_transaction_failed
        - invalid_exact_evm_payload_undeployed_smart_wallet
        - smart_wallet_deployment_failed
        - unsupported_payload_type
        - invalid_erc20_approval_extension_format
        - erc20_approval_tx_failed
        - erc20_approval_from_mismatch
        - erc20_approval_asset_mismatch
        - erc20_approval_spender_not_permit2
        - erc20_approval_tx_parse_failed
        - erc20_approval_tx_wrong_target
        - erc20_approval_tx_wrong_selector
        - erc20_approval_tx_wrong_spender
        - erc20_approval_tx_signer_mismatch
        - erc20_approval_tx_invalid_signature
        - invalid_exact_evm_unsupported_scheme
        - invalid_exact_evm_extra_field
        - invalid_exact_evm_payload_recipient_mismatch
        - invalid_exact_evm_insufficient_funds
        - invalid_exact_evm_transaction_state
        - invalid_permit2_spender
        - invalid_permit2_recipient_mismatch
        - permit2_deadline_expired
        - permit2_not_yet_valid
        - permit2_amount_mismatch
        - permit2_token_mismatch
        - invalid_permit2_signature
        - permit2_allowance_required
        - permit2_invalid_amount
        - permit2_invalid_destination
        - permit2_invalid_owner
        - permit2_payment_too_early
        - permit2_invalid_nonce
        - permit2_2612_amount_mismatch
        - permit2_simulation_failed
        - permit2_insufficient_balance
        - permit2_proxy_not_deployed
        - erc20_approval_insufficient_eth_for_gas
        - erc20_approval_broadcast_failed
        - invalid_exact_solana_unsupported_scheme
        - invalid_exact_solana_network_mismatch
        - invalid_exact_solana_payload_missing_fee_payer
        - invalid_exact_solana_fee_payer_not_managed_by_facilitator
        - invalid_exact_solana_payload_transaction
        - invalid_exact_solana_payload_transaction_could_not_be_decoded
        - invalid_exact_solana_payload_transaction_instructions_length
        - invalid_exact_solana_payload_unknown_fourth_instruction
        - invalid_exact_solana_payload_unknown_fifth_instruction
        - invalid_exact_solana_payload_unknown_sixth_instruction
        - invalid_exact_solana_payload_transaction_instructions_compute_limit_instruction
        - invalid_exact_solana_payload_transaction_instructions_compute_price_instruction
        - invalid_exact_solana_payload_transaction_instructions_compute_price_instruction_too_high
        - invalid_exact_solana_payload_no_transfer_instruction
        - invalid_exact_solana_payload_transaction_fee_payer_transferring_funds
        - invalid_exact_solana_payload_mint_mismatch
        - invalid_exact_solana_payload_recipient_mismatch
        - invalid_exact_solana_payload_amount_insufficient
        - invalid_exact_solana_invalid_fee_payer
        - invalid_exact_solana_transaction_signing_failed
        - invalid_exact_solana_transaction_simulation_failed
        - invalid_exact_solana_payload_memo_mismatch
        - invalid_exact_solana_payload_memo_count
        - invalid_exact_solana_verification_failed
        - invalid_exact_solana_fee_payer_mismatch
        - invalid_exact_solana_transaction_failed
        - invalid_exact_solana_transaction_confirmation_failed
        - duplicate_settlement
        - invalid_exact_solana_extra_field
        - batch_settlement_cumulative_amount_mismatch
        - batch_settlement_channel_busy
        - missing_batch_settlement_channel
        - batch_settlement_charge_exceeds_signed_cumulative
        - batch_settlement_refund_no_balance
        - batch_settlement_refund_amount_invalid
        - batch_settlement_refund_amount_exceeds_balance
        - amount_too_low
        - invalid_amount
        - kyt_risk_detected
        - permit2_disabled
        - preflight_validation_failed
        - request_blocked_by_location
        - self_send_not_allowed
        - invalid_bazaar_extension
        - unknown_error
      example: insufficient_funds
    x402SettlePaymentRejection:
      type: object
      description: The result when x402 payment settlement fails.
      properties:
        success:
          type: boolean
          description: Indicates whether the payment settlement is successful.
          example: false
        errorReason:
          $ref: '#/components/schemas/x402SettleErrorReason'
        errorMessage:
          type: string
          description: The message describing the error reason.
          example: Insufficient funds
        payer:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: |-
            The onchain address of the client that is paying for the resource.

            For EVM networks, the payer will be a 0x-prefixed, checksum EVM address.

            For Solana-based networks, the payer will be a base58-encoded Solana address.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        transaction:
          type: string
          description: |-
            The transaction of the settlement.
            For EVM networks, the transaction will be a 0x-prefixed, EVM transaction hash.
            For Solana-based networks, the transaction will be a base58-encoded Solana signature.
            Populated even though `success` is `false` when `errorReason` is `settlement_pending`: the transaction broadcast successfully but its receipt could not be retrieved, so the hash is returned for the caller to reconcile before retrying.
          pattern: ^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{87,88})$
          example: '0x89c91c789e57059b17285e7ba1716a1f5ff4c5dace0ea5a5135f26158d0421b9'
        network:
          type: string
          description: The network where the settlement occurred.
          example: base
      required:
        - success
        - errorReason
      example:
        success: false
        errorReason: insufficient_funds
        payer: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    x402SupportedPaymentKind:
      type: object
      description: The supported payment kind for the x402 protocol. A kind is comprised of a scheme and a network, which together uniquely identify a way to move money on the x402 protocol. For more details, please see [x402 Schemes](https://github.com/coinbase/x402?tab=readme-ov-file#schemes).
      properties:
        x402Version:
          $ref: '#/components/schemas/X402Version'
        scheme:
          type: string
          description: The scheme of the payment protocol.
          enum:
            - exact
            - upto
            - batch-settlement
          example: exact
        network:
          type: string
          description: 'The network of the blockchain. The format corresponds to the `x402Version` of the enclosing `x402SupportedPaymentKind`: v1 uses human-readable names (see `X402V1Network`); v2 uses CAIP-2 chain IDs (see `X402V2Network`).'
          example: base
          enum:
            - base-sepolia
            - base
            - solana-devnet
            - solana
            - eip155:8453
            - eip155:84532
            - eip155:137
            - eip155:42161
            - eip155:480
            - eip155:4801
            - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
            - solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
        extra:
          type: object
          description: |-
            The optional additional scheme-specific payment info.
            Common scheme-specific fields:
              - `exact` on Solana: `feePayer` — the base58-encoded Solana address that pays transaction fees.
              - `upto` on EVM: `name`, `version`, and `facilitatorAddress` — the EVM address of the facilitator that the client must bind into the Permit2 witness when constructing the payment payload.
              - `batch-settlement` on EVM: `name`, `version`, `receiverAuthorizer` (the EVM address authorized to sign claim batches), `withdrawDelay` (channel non-cooperative withdraw delay in seconds, 900–2,592,000), and optionally `assetTransferMethod` (e.g., `"eip3009"`).
          additionalProperties: true
          example:
            feePayer: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT
      required:
        - x402Version
        - scheme
        - network
    x402ResourceQuality:
      type: object
      description: Quality metrics for a discovered x402 resource.
      properties:
        l30DaysTotalCalls:
          type: integer
          description: Total number of paid calls to a resource in the last 30 days.
          example: 42
        l30DaysUniquePayers:
          type: integer
          description: Number of unique payers to a resource in the last 30 days.
          example: 15
        lastCalledAt:
          type: string
          format: date-time
          description: Timestamp of the most recent paid call to a resource.
          example: '2024-01-15T10:30:00Z'
      example:
        l30DaysTotalCalls: 42
        l30DaysUniquePayers: 15
        lastCalledAt: '2024-01-15T10:30:00Z'
    x402DiscoveryResource:
      type: object
      description: |
        A single discovered x402 resource. Its fields come from three sources:

        - **x402 protocol** — negotiated from the resource's payment-required response: `resource`,
          `type`, `x402Version`, `accepts`, `extensions`.
        - **Provider-supplied** — metadata published by the resource owner: `description`,
          `serviceName`, `tags`.
        - **Coinbase-derived** — added during ingestion and curation: `iconUrl`, `quality`,
          `lastUpdated`, and (for Coinbase-curated endpoints only) `curated`, `skillUrl` (a
          Coinbase-authored SKILL.md), and `bundleSlugs`.
      properties:
        resource:
          type: string
          description: The URL of the resource.
          example: https://api.example.com/weather/forecast
        description:
          type: string
          description: A human-readable description of the resource.
          example: Real-time weather forecast data
        type:
          type: string
          description: Communication protocol (e.g., "http", "mcp").
          enum:
            - http
            - mcp
          example: http
        x402Version:
          $ref: '#/components/schemas/X402Version'
        lastUpdated:
          type: string
          format: date-time
          description: Timestamp of the last update.
          example: '2024-01-15T10:30:00Z'
        accepts:
          type: array
          description: Payment requirements accepted by the resource.
          items:
            $ref: '#/components/schemas/x402PaymentRequirements'
          example:
            - scheme: exact
              network: eip155:8453
              amount: '1000000'
              payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
              maxTimeoutSeconds: 60
        extensions:
          type: object
          description: Map of x402 protocol extensions supported by the resource, keyed by extension name.
          additionalProperties: true
          example:
            bazaar:
              info:
                input:
                  type: http
                  method: GET
              schema: {}
        quality:
          $ref: '#/components/schemas/x402ResourceQuality'
        serviceName:
          type: string
          description: |
            Display name of the service this resource belongs to. This is a free-form
            label for grouping and presentation only — it is not a stable identifier, and two resources
            sharing the same `serviceName` are not guaranteed to belong to the same logical service.
          example: Weather API
        tags:
          type: array
          description: |
            Low-cardinality string labels associated with the resource for client-side
            filtering and display. Values are free-form (no controlled vocabulary) and case-sensitive.
            Order is not significant and duplicates are not expected.
          items:
            type: string
          example:
            - weather
            - data
        bundleSlugs:
          type: array
          maxItems: 50
          description: 'Slugs of the curated x402 bundles this resource belongs to. A bundle is an ordered, named grouping of curated resources covering a common agent workflow. Present only for Coinbase-curated resources (`curated: true`); omitted when the resource is not curated or is not a member of any bundle.'
          items:
            type: string
            maxLength: 64
            pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          example:
            - defi-trading
        iconUrl:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: |
            URL of a square icon representing the service this resource belongs to. Distinct from a
            brand logo: this is intended for compact, list-view rendering (favicon-style) and is
            normalized to a square aspect ratio at ingestion. The image is moderated and re-hosted by
            Coinbase, so the URL is stable and safe to render directly in clients. Omitted when the
            provider did not supply an icon, when the supplied icon failed moderation, or when image
            processing was unavailable at ingestion time.
          example: https://res.cloudinary.com/bdb-prod/image/upload/...
        curated:
          type: boolean
          description: |
            Whether this resource is a Coinbase-curated endpoint. Curated endpoints have passed the
            partner-admission and verification bar and surface higher in search and listing results.
            Omitted (treated as `false`) when the resource is not curated.
          example: true
        skillUrl:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: |
            URL of the SKILL.md document describing how to use this resource. Omitted when the resource
            has no associated skill document.
          example: https://skills.cdp.coinbase.com/weather-api/SKILL.md
      required:
        - resource
        - type
        - x402Version
    x402DiscoveryResourcesResponse:
      type: object
      description: Response containing discovered x402 resources.
      properties:
        x402Version:
          $ref: '#/components/schemas/X402Version'
        items:
          type: array
          description: List of discovered x402 resources.
          items:
            $ref: '#/components/schemas/x402DiscoveryResource'
          example:
            - resource: https://api.example.com/weather/forecast
              description: Real-time weather forecast data.
              type: http
              x402Version: 2
              lastUpdated: '2024-01-15T10:30:00Z'
              accepts:
                - scheme: exact
                  network: eip155:8453
                  amount: '1000000'
                  payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                  maxTimeoutSeconds: 60
              extensions:
                bazaar:
                  info:
                    input:
                      type: http
                      method: GET
                  schema: {}
              quality:
                l30DaysTotalCalls: 42
                l30DaysUniquePayers: 15
                lastCalledAt: '2024-01-15T10:30:00Z'
              serviceName: Weather API
              tags:
                - weather
                - data
              iconUrl: https://res.cloudinary.com/bdb-prod/image/upload/...
              curated: true
              skillUrl: https://skills.cdp.coinbase.com/weather-api/SKILL.md
        pagination:
          type: object
          description: Pagination information for the response.
          properties:
            limit:
              type: integer
              description: The number of discovered x402 resources to return per page.
              example: 100
            offset:
              type: integer
              description: The offset of the first discovered x402 resource to return.
              example: 0
            total:
              type: integer
              description: The total number of discovered x402 resources.
              example: 1000
          example:
            limit: 100
            offset: 0
            total: 1000
      required:
        - items
        - x402Version
        - pagination
    x402DiscoveryMerchantResponse:
      type: object
      description: Response containing x402 resources associated with a merchant payment address. The resources list is empty when no active resources are found.
      properties:
        x402Version:
          $ref: '#/components/schemas/X402Version'
        payTo:
          $ref: '#/components/schemas/BlockchainAddress'
        resources:
          type: array
          description: List of discovered x402 resources associated with the merchant's payTo address. This list is empty when no active resources are found.
          items:
            $ref: '#/components/schemas/x402DiscoveryResource'
          example:
            - resource: https://api.example.com/premium/data
              description: Premium API access for data analysis.
              type: http
              x402Version: 2
              lastUpdated: '2024-01-15T10:30:00Z'
              accepts:
                - scheme: exact
                  network: eip155:8453
                  amount: '1000000'
                  payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                  maxTimeoutSeconds: 60
              extensions:
                bazaar:
                  info:
                    input:
                      type: http
                      method: POST
                  schema: {}
              quality:
                l30DaysTotalCalls: 42
                l30DaysUniquePayers: 15
                lastCalledAt: '2024-01-15T10:30:00Z'
              serviceName: Premium Data API
              tags:
                - data
                - analytics
              iconUrl: https://res.cloudinary.com/bdb-prod/image/upload/...
              curated: true
              skillUrl: https://skills.cdp.coinbase.com/premium-data-api/SKILL.md
        pagination:
          type: object
          description: Pagination information for the response.
          properties:
            limit:
              type: integer
              description: The number of resources returned per page.
              example: 20
            offset:
              type: integer
              description: The offset of the first resource returned.
              example: 0
            total:
              type: integer
              description: The total number of resources associated with the merchant's payTo address.
              example: 10
          example:
            limit: 20
            offset: 0
            total: 10
      required:
        - x402Version
        - payTo
        - resources
        - pagination
    x402SearchResourcesResponse:
      type: object
      description: Response from a search for x402 resources.
      properties:
        resources:
          type: array
          description: List of x402 resources matching the search query and filters.
          items:
            $ref: '#/components/schemas/x402DiscoveryResource'
          example:
            - resource: https://api.example.com/weather/forecast
              description: Real-time weather forecast data.
              type: http
              x402Version: 2
              lastUpdated: '2024-01-15T10:30:00Z'
              accepts:
                - scheme: exact
                  network: eip155:8453
                  amount: '1000000'
                  payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                  asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
                  maxTimeoutSeconds: 60
              extensions:
                bazaar:
                  info:
                    input:
                      type: http
                      method: GET
                  schema: {}
              quality:
                l30DaysTotalCalls: 42
                l30DaysUniquePayers: 15
                lastCalledAt: '2024-01-15T10:30:00Z'
              serviceName: Weather API
              tags:
                - weather
                - data
              iconUrl: https://res.cloudinary.com/bdb-prod/image/upload/...
              curated: true
              skillUrl: https://skills.cdp.coinbase.com/weather-api/SKILL.md
        partialResults:
          type: boolean
          description: Indicates whether the result set was truncated because there were more results than the requested limit.
          example: false
        searchMethod:
          type: string
          description: The search method used to retrieve the results (e.g., "text", "vector", "hybrid").
          enum:
            - text
            - vector
            - hybrid
          example: text
        x402Version:
          $ref: '#/components/schemas/X402Version'
      required:
        - resources
        - partialResults
        - x402Version
    x402McpRequest:
      type: object
      description: A JSON-RPC 2.0 request for the Model Context Protocol.
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version, must be "2.0".
          example: '2.0'
        id:
          oneOf:
            - type: string
            - type: integer
          description: Request identifier.
          example: 1
        method:
          type: string
          description: The MCP method to invoke.
          example: tools/list
        params:
          type: object
          description: Optional parameters for the method.
          additionalProperties: true
          example: {}
      required:
        - jsonrpc
        - method
    x402McpError:
      type: object
      description: JSON-RPC 2.0 error object.
      properties:
        code:
          type: integer
          description: Error code.
          example: -32600
        message:
          type: string
          description: Error message.
          example: Invalid Request
        data:
          type: object
          description: Additional error data.
          additionalProperties: true
          example: {}
      required:
        - code
        - message
      example:
        code: -32600
        message: Invalid Request
        data: {}
    x402McpResponse:
      type: object
      description: A JSON-RPC 2.0 response for the Model Context Protocol.
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version.
          example: '2.0'
        id:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: Request identifier (matches the request ID, null for notifications).
          example: 1
        result:
          type: object
          description: The result of the method call (present on success).
          additionalProperties: true
          example:
            tools: []
        error:
          $ref: '#/components/schemas/x402McpError'
      required:
        - jsonrpc
    x402Bundle:
      type: object
      description: 'A curated workflow bundle: an ordered, named grouping of curated x402 resources that together cover a common agent workflow. This metadata shape is returned by the bundle list endpoint; the per-bundle detail endpoint additionally returns the joined member resources.'
      properties:
        slug:
          type: string
          maxLength: 64
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: The stable, unique, URL-safe identifier for the bundle. Used as the path segment in `GET /v2/x402/discovery/bundles/{bundleSlug}`.
          example: defi-trading
        name:
          type: string
          description: The human-readable display name of the bundle.
          example: DeFi Trading
        description:
          type: string
          description: A human-readable description of the workflow the bundle covers.
          example: Endpoints for discovering prices, routing swaps, and settling trades onchain.
      required:
        - slug
        - name
    x402BundlesResponse:
      type: object
      description: Response containing the available curated x402 bundles. Unlike x402 protocol discovery and search responses, bundle responses omit `x402Version` because bundles are CDP-curated metadata, not protocol negotiation payloads.
      properties:
        bundles:
          type: array
          maxItems: 50
          description: The list of available curated bundles. This list is empty when no bundles are defined.
          items:
            $ref: '#/components/schemas/x402Bundle'
          example:
            - slug: defi-trading
              name: DeFi Trading
              description: Endpoints for discovering prices, routing swaps, and settling trades onchain.
            - slug: market-data
              name: Market Data
              description: Endpoints for real-time and historical market data.
      required:
        - bundles
    x402BundleResponse:
      type: object
      description: Response containing a single curated bundle's metadata and its ordered member resources. Members are the bundle's curated endpoints joined to their full discovery metadata, in bundle-defined order. Unlike x402 protocol discovery and search responses, bundle responses omit `x402Version` because bundles are CDP-curated metadata, not protocol negotiation payloads.
      allOf:
        - $ref: '#/components/schemas/x402Bundle'
        - type: object
          properties:
            resources:
              type: array
              maxItems: 50
              description: The bundle's member resources in bundle-defined order. Each entry is the full discovery metadata for a curated endpoint belonging to this bundle. Bundle membership is capped at 50 resources.
              items:
                $ref: '#/components/schemas/x402DiscoveryResource'
              example:
                - resource: https://api.example.com/prices
                  description: Real-time token prices.
                  type: http
                  x402Version: 2
                  curated: true
                  skillUrl: https://skills.cdp.coinbase.com/prices-api/SKILL.md
          required:
            - resources
    HttpsUrl:
      type: string
      format: uri
      minLength: 12
      maxLength: 2048
      pattern: ^https://.*$
      description: A valid HTTPS URL.
      example: https://example.com
    x402ValidateRequest:
      type: object
      description: Request to validate an x402 endpoint's bazaar-discovery configuration.
      properties:
        resource:
          allOf:
            - $ref: '#/components/schemas/HttpsUrl'
          description: HTTPS URL of the x402 endpoint to validate. Must use the `https://` scheme.
          example: https://api.example.com/weather/forecast
        method:
          type: string
          description: The HTTP method used to probe the endpoint. Only GET and POST are supported; other verbs are intentionally rejected because x402 resources are expected to respond to these methods.
          enum:
            - GET
            - POST
          default: GET
          example: GET
      required:
        - resource
      example:
        resource: https://api.example.com/weather/forecast
        method: GET
    x402ValidateCheck:
      type: object
      description: The result of a single preflight check performed against the x402 endpoint.
      properties:
        check:
          type: string
          description: The name of the preflight check. New values may be added in future versions; clients should handle unknown values gracefully.
          enum:
            - reachable
            - returns_402
            - has_bazaar_extension
            - parse
          example: returns_402
        passed:
          type: boolean
          description: Whether the check passed.
          example: true
        detail:
          type: string
          description: A human-readable explanation of the check result.
          example: Endpoint responded with HTTP 402 Payment Required.
        expected:
          type: string
          description: The value the check expected, when applicable.
          example: '402'
        actual:
          type: string
          description: The value the check observed, when applicable.
          example: '402'
        severity:
          type: string
          enum:
            - required
            - advisory
          description: Whether this check is a hard indexing requirement or a quality recommendation. A `required` check affects validity when it fails. An `advisory` check (for example, a missing output schema) is a suggestion to improve discoverability and does not make the endpoint invalid.
          example: required
      required:
        - check
        - passed
        - detail
        - severity
      example:
        check: returns_402
        passed: true
        detail: Endpoint responded with HTTP 402 Payment Required.
        expected: '402'
        actual: '402'
        severity: required
    x402ValidateSimulation:
      type: object
      description: The simulated facilitator decision for the x402 endpoint.
      properties:
        outcome:
          type: string
          description: 'The simulated facilitator outcome: `accepted` if the facilitator would index the resource, or `rejected` if it would reject it.'
          enum:
            - accepted
            - rejected
          example: accepted
        rejectionReason:
          type: string
          description: The reason the resource would be rejected, present only when `outcome` is `rejected`.
          example: Resource is missing a supported payment scheme.
      required:
        - outcome
      example:
        outcome: accepted
    x402ValidateIndex:
      type: object
      description: Bazaar index status for a validated x402 endpoint.
      properties:
        active:
          type: boolean
          description: Whether the indexed resource is active and served in discovery results.
          example: true
        lastCrawledAt:
          type: string
          format: date-time
          nullable: true
          description: When the endpoint was last crawled, or `null` if it has been indexed but not yet crawled.
          example: '2026-06-01T12:00:00Z'
        quality:
          allOf:
            - $ref: '#/components/schemas/x402ResourceQuality'
          description: Quality metrics for the indexed resource, present only when the endpoint has call history.
      required:
        - active
        - lastCrawledAt
      example:
        active: true
        lastCrawledAt: '2026-06-01T12:00:00Z'
        quality:
          l30DaysTotalCalls: 42
          l30DaysUniquePayers: 15
          lastCalledAt: '2026-06-01T12:00:00Z'
    x402ValidateResponse:
      type: object
      description: Response from validating an x402 endpoint's bazaar-discovery configuration.
      properties:
        valid:
          type: boolean
          description: 'Whether the endpoint is valid: all preflight checks passed and the facilitator would index the resource.'
          example: true
        statusCode:
          type: integer
          nullable: true
          description: The HTTP status code returned by the endpoint, or `null` if the endpoint was not reachable.
          example: 402
        x402Version:
          type: integer
          nullable: true
          description: The x402 protocol version advertised by the endpoint, or `null` if it could not be determined. Intentionally a bare integer rather than the `X402Version` enum so the validator can surface unsupported or malformed version values returned by non-conforming endpoints.
          example: 2
        preflight:
          type: array
          description: All check results in run order. Well-known check names are `reachable`, `returns_402`, `has_bazaar_extension`, and `parse`. Additional checks may be added in future versions.
          items:
            $ref: '#/components/schemas/x402ValidateCheck'
        paymentRequirements:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/x402PaymentRequirements'
          description: The raw decoded payment requirements returned by the endpoint, or `null` if the endpoint was not reachable or did not return a parseable 402 payload. Lets sellers inspect exactly what their endpoint is advertising.
        bazaarExtension:
          type: object
          nullable: true
          additionalProperties: true
          description: The `extensions.bazaar` block from the endpoint's discovery metadata, or `null` if the bazaar extension was absent or the endpoint was not reachable. Lets sellers verify the discovery configuration their endpoint is advertising.
          example:
            info:
              input:
                type: http
                method: GET
            schema: {}
        simulation:
          $ref: '#/components/schemas/x402ValidateSimulation'
        index:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/x402ValidateIndex'
          description: Bazaar index status for the endpoint, or `null` if the endpoint is not yet indexed. Present on every response regardless of simulation outcome.
      required:
        - valid
        - statusCode
        - x402Version
        - preflight
        - paymentRequirements
        - bazaarExtension
        - simulation
        - index
      example:
        valid: true
        statusCode: 402
        x402Version: 2
        preflight:
          - check: reachable
            passed: true
            detail: Endpoint responded within the timeout.
            severity: required
          - check: returns_402
            passed: true
            detail: Endpoint responded with HTTP 402 Payment Required.
            expected: '402'
            actual: '402'
            severity: required
          - check: has_bazaar_extension
            passed: true
            detail: Payment requirements include the bazaar discovery extension.
            severity: required
          - check: parse
            passed: true
            detail: Payment requirements parsed successfully.
            severity: required
        paymentRequirements:
          scheme: exact
          network: base
          maxAmountRequired: '100000'
          resource: https://api.example.com/weather/forecast
          description: Real-time weather forecast data.
          mimeType: application/json
          payTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
          asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
          maxTimeoutSeconds: 60
        bazaarExtension:
          info:
            input:
              type: http
              method: GET
          schema: {}
        simulation:
          outcome: accepted
        index:
          active: true
          lastCrawledAt: '2026-06-01T12:00:00Z'
          quality:
            l30DaysTotalCalls: 42
            l30DaysUniquePayers: 15
            lastCalledAt: '2026-06-01T12:00:00Z'
    InitiateOnrampVerificationRequest:
      type: object
      description: Request body for initiating an onramp OTP verification.
      properties:
        channel:
          description: The OTP delivery channel.
          type: string
          enum:
            - sms
            - email
          example: sms
        destination:
          description: The phone number or email address to send the OTP to.
          oneOf:
            - $ref: '#/components/schemas/PhoneNumber'
            - $ref: '#/components/schemas/Email'
          example: '+12055555555'
      required:
        - channel
        - destination
    OnrampVerificationId:
      type: string
      description: A unique identifier for an onramp verification record, in the format `onramp_verification_<uuid>`.
      pattern: ^onramp_verification_[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      example: onramp_verification_a1b2c3d4-e5f6-7890-abcd-ef1234567890
    OnrampVerificationInitiation:
      type: object
      description: The result of initiating an onramp OTP verification.
      properties:
        verificationId:
          allOf:
            - $ref: '#/components/schemas/OnrampVerificationId'
          description: Identifier returned by this endpoint. Pass to the Submit Onramp Verification endpoint along with the OTP code within 10 minutes.
          example: onramp_verification_a1b2c3d4-e5f6-7890-abcd-ef1234567890
        otpExpiresAt:
          description: The deadline for submitting the OTP code (10 minutes from now).
          type: string
          format: date-time
          example: '2025-04-24T00:10:00Z'
      required:
        - verificationId
        - otpExpiresAt
    SubmitOnrampVerificationRequest:
      type: object
      description: Request body for submitting an OTP code to complete an onramp verification.
      properties:
        otpCode:
          description: The 6-digit OTP code the user received.
          type: string
          pattern: ^\d{6}$
          example: '123456'
      required:
        - otpCode
    OnrampVerificationConfirmation:
      type: object
      description: The result of successfully submitting an onramp OTP verification.
      properties:
        verificationId:
          allOf:
            - $ref: '#/components/schemas/OnrampVerificationId'
          description: The same verification ID. Store on the user's device and pass to the Create Onramp Order endpoint. Valid for 60 days.
          example: onramp_verification_a1b2c3d4-e5f6-7890-abcd-ef1234567890
        verificationExpiresAt:
          description: The date and time when this verification expires for order placement.
          type: string
          format: date-time
          example: '2025-06-23T00:00:00Z'
      required:
        - verificationId
        - verificationExpiresAt
    OnrampOrderPaymentMethodTypeId:
      type: string
      description: The type of payment method to be used to complete an onramp order.
      enum:
        - GUEST_CHECKOUT_APPLE_PAY
        - GUEST_CHECKOUT_GOOGLE_PAY
      example: GUEST_CHECKOUT_APPLE_PAY
    OnrampUserAuthToken:
      type: string
      description: |-
        A reusable, PII-free token issued after a user completes verification in the embedded onramp flow. It encodes only the underlying verification IDs, no personal information. Pass it on subsequent orders to take a returning user straight to the pay button, skipping OTP when checking out to the same wallet.

        In the embedded flow, `phoneNumber`, `email`, `phoneNumberVerifiedAt`, and `agreementAcceptedAt` are handled by Coinbase in the hosted popup and may be omitted from the request even though they are required for the standard partner-verified flow. Reuse is best-effort: an invalid, expired, or different-wallet token still requires the user to verify. Valid for 60 days.
      example: eyJ2ZXJpZmljYXRpb25JZHMiOlsidl9hYmMxMjMiLCJ2X2RlZjQ1NiJdfQ==
    OnrampOrderFee:
      type: object
      description: A fee associated with an order.
      properties:
        type:
          type: string
          enum:
            - FEE_TYPE_NETWORK
            - FEE_TYPE_EXCHANGE
          description: The type of fee.
          example: FEE_TYPE_NETWORK
        amount:
          type: string
          description: The amount of the fee.
          example: '0.95'
        currency:
          type: string
          description: The currency of the fee.
          example: USDC
      required:
        - type
        - amount
        - currency
    OnrampOrderStatus:
      type: string
      description: The status of an onramp order.
      enum:
        - ONRAMP_ORDER_STATUS_PENDING_AUTH
        - ONRAMP_ORDER_STATUS_PENDING_VERIFICATION
        - ONRAMP_ORDER_STATUS_PENDING_PAYMENT
        - ONRAMP_ORDER_STATUS_PROCESSING
        - ONRAMP_ORDER_STATUS_COMPLETED
        - ONRAMP_ORDER_STATUS_FAILED
      example: ONRAMP_ORDER_STATUS_COMPLETED
    OnrampOrder:
      type: object
      description: An Onramp order.
      properties:
        orderId:
          type: string
          description: The ID of the onramp order.
          example: 123e4567-e89b-12d3-a456-426614174000
        paymentTotal:
          type: string
          description: The total amount of fiat to be paid, inclusive of any fees.
          example: '100.75'
        paymentSubtotal:
          type: string
          description: The amount of fiat to be converted to crypto.
          example: '100'
        paymentCurrency:
          type: string
          description: The fiat currency to be converted to crypto.
          example: USD
        paymentMethod:
          $ref: '#/components/schemas/OnrampOrderPaymentMethodTypeId'
        purchaseAmount:
          type: string
          description: The amount of crypto to be purchased.
          example: '100.000000'
        purchaseCurrency:
          type: string
          description: The crypto currency to be purchased.
          example: USDC
        fees:
          type: array
          description: The fees associated with the order.
          items:
            $ref: '#/components/schemas/OnrampOrderFee'
          example:
            - type: FEE_TYPE_EXCHANGE
              amount: '0.5'
              currency: USD
            - type: FEE_TYPE_NETWORK
              amount: '0.25'
              currency: USD
        exchangeRate:
          type: string
          description: The exchange rate used to convert fiat to crypto i.e. the crypto value of one fiat.
          example: '1'
        destinationAddress:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: The destination address to send the crypto to.
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
        destinationNetwork:
          type: string
          description: The network to send the crypto on.
          example: base
        status:
          $ref: '#/components/schemas/OnrampOrderStatus'
        txHash:
          type: string
          description: The transaction hash of the order (only available once crypto has been sent).
          example: '0x363cd3b3d4f49497cf5076150cd709307b90e9fc897fdd623546ea7b9313cecb'
        createdAt:
          type: string
          description: The date and time the order was created.
          example: '2025-04-24T00:00:00Z'
        updatedAt:
          type: string
          description: The date and time the order was last updated.
          example: '2025-04-24T00:00:00Z'
        partnerUserRef:
          type: string
          description: The partner user reference ID.
          example: user123
      required:
        - orderId
        - paymentTotal
        - paymentSubtotal
        - paymentCurrency
        - paymentMethod
        - purchaseAmount
        - purchaseCurrency
        - fees
        - exchangeRate
        - destinationAddress
        - destinationNetwork
        - status
        - createdAt
        - updatedAt
    OnrampPaymentLinkType:
      type: string
      description: The type of payment link.
      enum:
        - PAYMENT_LINK_TYPE_APPLE_PAY_BUTTON
        - PAYMENT_LINK_TYPE_GOOGLE_PAY_BUTTON
        - PAYMENT_LINK_TYPE_EMBEDDED_ORDER
      example: PAYMENT_LINK_TYPE_APPLE_PAY_BUTTON
    OnrampPaymentLink:
      type: object
      description: |-
        A payment link to pay for an order.

        Please refer to the [Onramp docs](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/onramp-overview) for details on how to integrate with the different payment link types.
      properties:
        url:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: The URL to the hosted widget the user should be redirected to. For certain payment link types you can append your own redirect_url query parameter to this URL to ensure the user is redirected back to your app after the widget completes.
          example: https://pay.coinbase.com/v2/api-onramp/apple-pay?sessionToken=MWYwNWQwODktZTZlYy02OTdlLTgzZTYtMTI3NzcyOWJhNjM3
        paymentLinkType:
          $ref: '#/components/schemas/OnrampPaymentLinkType'
      required:
        - url
        - paymentLinkType
    OnrampQuotePaymentMethodTypeId:
      type: string
      description: The type of payment method used to generate the onramp quote.
      enum:
        - CARD
        - ACH
        - APPLE_PAY
        - PAYPAL
        - FIAT_WALLET
        - CRYPTO_WALLET
      example: CARD
    Uri:
      type: string
      format: uri
      minLength: 5
      maxLength: 2048
      pattern: ^.*://.*$
      description: A valid URI.
      example: foo://bar
    OnrampSessionRequest:
      type: object
      description: Common request parameters shared by [Create Onramp Session](#operation/createOnrampSession) and [Create Onramp Mobile Challenge](#operation/createOnrampMobileChallenge).
      properties:
        purchaseCurrency:
          description: |-
            The ticker (e.g. `BTC`, `USDC`, `SOL`) or the Coinbase UUID (e.g. `d85dce9b-5b73-5c3c-8978-522ce1d1c1b4`) of the crypto asset to be purchased.

            Use the [Onramp Buy Options API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-buy-options) to discover the supported purchase currencies for your user's location.
          type: string
          example: USDC
        destinationNetwork:
          description: |-
            The name of the crypto network the purchased currency will be sent on.

            Use the [Onramp Buy Options API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-buy-options) to discover the supported networks for your user's location.
          type: string
          example: base
        destinationAddress:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          description: The address the purchased crypto will be sent to.
          example: '0x1234567890abcdef1234567890abcdef12345678'
        paymentAmount:
          description: A string representing the amount of fiat the user wishes to pay in exchange for crypto. When using this parameter, the returned quote will be inclusive of fees i.e. the user will pay this exact amount of the payment currency.
          type: string
          example: '100.00'
        purchaseAmount:
          description: A string representing the amount of crypto the user wishes to purchase. When using this parameter, the returned quote will be exclusive of fees i.e. the user will receive this exact amount of the purchase currency.
          type: string
          example: '10.000000'
        paymentCurrency:
          description: The fiat currency to be converted to crypto.
          type: string
          example: USD
        paymentMethod:
          $ref: '#/components/schemas/OnrampQuotePaymentMethodTypeId'
        country:
          description: The ISO 3166-1 two letter country code (e.g. US).
          type: string
          example: US
        subdivision:
          description: The ISO 3166-2 two letter state code (e.g. NY). Only required for US.
          type: string
          example: NY
        redirectUrl:
          allOf:
            - $ref: '#/components/schemas/Uri'
          description: URI to redirect the user to after they complete or dismiss the transaction. Embedded in the returned onramp URL as a query parameter.
          example: https://example.com/success
        clientIp:
          description: The IP address of the end user requesting the onramp transaction.
          type: string
          example: 127.0.0.1
        partnerUserRef:
          description: |-
            A unique string that represents the user in your app. This can be used to link individual transactions together so you can retrieve the transaction history for your users. Prefix this string with "sandbox-" (e.g. "sandbox-user-1234") to perform a sandbox transaction which will allow you to test your integration without any real transfer of funds.

            This value can be used with the [Onramp User Transactions API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-onramp-transactions-by-id) to retrieve all transactions created by the user.
          type: string
          example: user-1234
      required:
        - destinationAddress
        - purchaseCurrency
        - destinationNetwork
    OnrampSession:
      type: object
      description: An onramp session containing a ready-to-use onramp URL.
      properties:
        onrampUrl:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: Ready-to-use onramp URL.
          example: https://pay.coinbase.com/buy?sessionToken=abc123F
      required:
        - onrampUrl
      example:
        onrampUrl: https://pay.coinbase.com/buy?sessionToken=abc123F
    OnrampQuote:
      type: object
      description: Quote information with pricing details for the crypto purchase.
      properties:
        paymentTotal:
          type: string
          description: The total amount of fiat to be paid, inclusive of any fees.
          example: '100.75'
        paymentSubtotal:
          type: string
          description: The amount of fiat to be converted to crypto.
          example: '100.00'
        paymentCurrency:
          type: string
          description: The fiat currency to be converted to crypto.
          example: USD
        purchaseAmount:
          type: string
          description: The amount of crypto to be purchased.
          example: '100.000000'
        purchaseCurrency:
          type: string
          description: The crypto currency to be purchased.
          example: USDC
        destinationNetwork:
          type: string
          description: The network to send the crypto on.
          example: base
        fees:
          type: array
          description: The fees associated with the quote.
          items:
            $ref: '#/components/schemas/OnrampOrderFee'
          example:
            - type: FEE_TYPE_EXCHANGE
              amount: '0.5'
              currency: USD
            - type: FEE_TYPE_NETWORK
              amount: '0.25'
              currency: USD
        exchangeRate:
          type: string
          description: The exchange rate used to convert fiat to crypto i.e. the crypto value of one fiat.
          example: '1'
      required:
        - paymentTotal
        - paymentSubtotal
        - paymentCurrency
        - purchaseAmount
        - purchaseCurrency
        - destinationNetwork
        - fees
        - exchangeRate
      example:
        paymentTotal: '100.75'
        paymentSubtotal: '100.00'
        paymentCurrency: USD
        purchaseAmount: '100.000000'
        purchaseCurrency: USDC
        destinationNetwork: base
        fees:
          - type: FEE_TYPE_EXCHANGE
            amount: '0.5'
            currency: USD
          - type: FEE_TYPE_NETWORK
            amount: '0.25'
            currency: USD
        exchangeRate: '1'
    OnrampUserIdType:
      type: string
      description: |
        The type of user identifier:
        - `phone_number`: A phone number in E.164 format associated with an onramp user.
      enum:
        - phone_number
      example: phone_number
    OnrampLimitType:
      type: string
      description: |
        The type of limit:
        - `weekly_spending`: Rolling 7-day spending limit. The limit applies to the sum of all completed transactions 
          within a sliding 168-hour (7-day) window. As time passes, older transactions naturally expire from the window. 
          $500 is the default limit.
        - `lifetime_transactions`: All-time transaction count limit. Tracks the total number of completed transactions 
          across the user's entire history with no time-based expiration. Once the limit is reached, no further 
          transactions are allowed. 15 is the default limit.
      enum:
        - weekly_spending
        - lifetime_transactions
      example: weekly_spending
    OnrampUserLimit:
      type: object
      description: A single limit with remaining capacity.
      properties:
        limitType:
          $ref: '#/components/schemas/OnrampLimitType'
        currency:
          type: string
          description: The currency of the limit amounts. Only present for spending limits, not for count-based limits.
          example: USD
        limit:
          type: string
          description: The maximum limit value.
          example: '2500'
        remaining:
          type: string
          description: The remaining amount or count available.
          example: '2000'
      required:
        - limitType
        - limit
        - remaining
    OnrampLimitUpgradeStatus:
      type: string
      description: |
        The status of verification:
        - `unrequested`: The limit upgrade has not been submitted.
        - `resubmit`: One or more identity fields must be resubmitted.
        - `pending`: The submitted identity fields are pending review.
        - `active`: The limit upgrade is active.
        - `inactive`: The limit upgrade was rejected and cannot be resubmitted.
      enum:
        - unrequested
        - resubmit
        - pending
        - active
        - inactive
      example: unrequested
    OnrampLimitUpgradeIdentityFieldKey:
      type: string
      description: |
        The identity field key for limit upgrades. These keys correspond to the fields
        in the limits upgrade request:
        - `ssnLast4`: Last 4 digits of the Social Security Number
        - `dateOfBirth`: Date of birth
      enum:
        - ssnLast4
        - dateOfBirth
      example: ssnLast4
    OnrampLimitUpgrade:
      type: object
      description: Describes a limit value associated with an upgrade.
      properties:
        limitType:
          $ref: '#/components/schemas/OnrampLimitType'
        maxUpgrade:
          type: string
          description: The maximum limit value possible after completing the upgrade. Risk factors may impact the actual limit value that takes effect. For `lifetime_transactions`, `2147483647` represents an unlimited number of transactions.
          example: '2500'
      required:
        - limitType
        - maxUpgrade
    OnrampLimitUpgradeOption:
      type: object
      description: Describes the current status and potential limit changes for a limit upgrade.
      properties:
        status:
          $ref: '#/components/schemas/OnrampLimitUpgradeStatus'
        fields:
          type: array
          description: The identity fields associated with the current status. Contains fields to submit for `unrequested` and `resubmit`, fields pending review for `pending`, and is empty for `active` and `inactive`.
          items:
            $ref: '#/components/schemas/OnrampLimitUpgradeIdentityFieldKey'
          example:
            - ssnLast4
            - dateOfBirth
        limitUpgrades:
          type: array
          description: The limit values associated with this upgrade.
          items:
            $ref: '#/components/schemas/OnrampLimitUpgrade'
          example:
            - limitType: weekly_spending
              maxUpgrade: '2500'
            - limitType: lifetime_transactions
              maxUpgrade: '2147483647'
      required:
        - status
        - fields
        - limitUpgrades
    OnrampLimitUpgradeInteractionMode:
      type: string
      description: |
        The interaction mode for the limit upgrade request:
        - `api`: Submit identity fields directly in the API request.
        - `embedded`: Return a Coinbase-hosted URL where the user enters identity fields.
      enum:
        - api
        - embedded
      x-enum-varnames:
        - OnrampLimitUpgradeInteractionModeAPI
        - OnrampLimitUpgradeInteractionModeEmbedded
      example: api
    OnrampLimitUpgradeIdentityFields:
      type: object
      description: Populate the properties that correspond to the `fields` array from the user's `OnrampLimitUpgradeOption`.
      properties:
        ssnLast4:
          type: string
          description: Last 4 digits of the Social Security Number (no dashes or spaces).
          example: '5678'
        dateOfBirth:
          allOf:
            - $ref: '#/components/schemas/DateOfBirth'
          description: Date of birth.
      example:
        ssnLast4: '5678'
        dateOfBirth:
          day: '15'
          month: '08'
          year: '1990'
    OnrampLimitUpgradeRequest:
      type: object
      description: Request to request a limits upgrade for a user.
      properties:
        userId:
          type: string
          description: The user identifier value. For `phone_number` type, this must be in E.164 format.
          example: '+12055555555'
        userIdType:
          $ref: '#/components/schemas/OnrampUserIdType'
        interactionMode:
          allOf:
            - $ref: '#/components/schemas/OnrampLimitUpgradeInteractionMode'
          default: api
          description: The interaction mode for the limit upgrade request. Defaults to `api`.
          example: api
        fields:
          $ref: '#/components/schemas/OnrampLimitUpgradeIdentityFields'
          description: Populate the properties that correspond to the `fields` array from the user's `OnrampLimitUpgradeOption`. Required in `api` mode. Omit in `embedded` mode — the user enters their identity information on the Coinbase-hosted upgrade page (see `interactionMode`), so any value sent here is rejected.
      required:
        - userId
        - userIdType
      example:
        userId: '+12055555555'
        userIdType: phone_number
        fields:
          ssnLast4: '5678'
          dateOfBirth:
            day: '15'
            month: '08'
            year: '1990'
    OnrampLimitUpgradeEmbeddedResponse:
      type: object
      description: A Coinbase-hosted URL for collecting limit upgrade identity fields.
      properties:
        upgradeUrl:
          allOf:
            - $ref: '#/components/schemas/Url'
          description: The Coinbase-hosted URL where the user enters identity information for the limit upgrade. Treat the session token in this URL as opaque.
          example: https://pay.coinbase.com/v2/api-onramp/upgrade-limits?sessionToken=MWYwNWQwODktZTZlYy02OTdlLTgzZTYtMTI3NzcyOWJhNjM3
        expiresAt:
          type: string
          format: date-time
          description: The time at which the hosted limit upgrade URL expires. Request a new upgrade URL after this time.
          example: '2026-06-21T00:05:00Z'
      required:
        - upgradeUrl
        - expiresAt
    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'
    OnchainActivityEventParameters:
      type: object
      description: Decoded event parameters from the contract event. Keys correspond to the named arguments in the event signature (e.g., `from`, `to`, `value` for an ERC-20 `Transfer`). Values are returned as strings to preserve precision for large integers and to avoid loss for address types. The exact set of keys depends on the contract event.
      additionalProperties:
        type: string
      example:
        from: '0xF33a96b5932D9E9B9A0eDA447AbD8C9d48d2e0c8'
        to: '0x61040E143A77F165Ba44543AF4A079F2C809D14b'
        value: '474891138228179365'
    OnchainActivityDetectedEvent:
      type: object
      x-event-type: onchain.activity.detected
      description: The payload delivered when onchain activity matching your subscription filters is detected. Each event corresponds to a single decoded contract log emitted onchain. The set of keys in `parameters` varies by the contract event being decoded (e.g., `Transfer(address,address,uint256)`).
      properties:
        block_number:
          type: integer
          format: int64
          description: The block number containing the transaction that emitted the event.
          example: 46218191
        contract_address:
          type: string
          description: The contract address that emitted the event.
          example: '0x940181a94A35A4569E4529A3CDfB74e38FD98631'
        event_name:
          type: string
          description: The name of the decoded contract event.
          example: Transfer
        event_signature:
          type: string
          description: The canonical event signature used to decode the log, including parameter types (e.g., `Transfer(address,address,uint256)`).
          example: Transfer(address,address,uint256)
        log_index:
          type: integer
          format: int64
          description: The zero-based index of the log within the transaction.
          example: 29
        network:
          type: string
          description: The blockchain network where the activity was detected.
          example: base-mainnet
        parameters:
          $ref: '#/components/schemas/OnchainActivityEventParameters'
        timestamp:
          type: string
          format: date-time
          description: The block timestamp of the transaction (ISO 8601 format).
          example: '2026-05-19T21:22:10Z'
        transaction_from:
          type: string
          description: The address that initiated the transaction (the transaction sender).
          example: '0x3E16D476D8Df15e3E776EAa5A46f37EC44C830cD'
        transaction_hash:
          type: string
          description: The hash of the transaction that emitted the event.
          example: '0xa58e4471bcce875b1ea49cc0864a620d3a484b9b7c1b0b4fd18ce83f5b30e5e0'
        transaction_to:
          type: string
          description: The address the transaction was sent to (typically a contract address).
          example: '0x61040E143A77F165Ba44543AF4A079F2C809D14b'
      required:
        - block_number
        - contract_address
        - event_name
        - event_signature
        - log_index
        - network
        - parameters
        - timestamp
        - transaction_from
        - transaction_hash
        - transaction_to
      example:
        block_number: 46218191
        contract_address: '0x940181a94A35A4569E4529A3CDfB74e38FD98631'
        event_name: Transfer
        event_signature: Transfer(address,address,uint256)
        log_index: 29
        network: base-mainnet
        parameters:
          from: '0xF33a96b5932D9E9B9A0eDA447AbD8C9d48d2e0c8'
          to: '0x61040E143A77F165Ba44543AF4A079F2C809D14b'
          value: '474891138228179365'
        timestamp: '2026-05-19T21:22:10Z'
        transaction_from: '0x3E16D476D8Df15e3E776EAa5A46f37EC44C830cD'
        transaction_hash: '0xa58e4471bcce875b1ea49cc0864a620d3a484b9b7c1b0b4fd18ce83f5b30e5e0'
        transaction_to: '0x61040E143A77F165Ba44543AF4A079F2C809D14b'
    OnchainActivityEventData:
      type: object
      description: Decoded blockchain event data for the wallet activity webhook. The exact fields depend on the type of onchain activity detected. Common fields include network, block info, and transaction hash. Additional fields are event-specific (e.g., `from`, `to`, `value` for transfers).
      properties:
        network:
          type: string
          description: The blockchain network where the activity was detected.
          example: base-mainnet
        blockNumber:
          type: string
          description: The block number containing the transaction.
          example: '12345678'
        blockTimestamp:
          type: string
          format: date-time
          description: The timestamp of the block.
          example: '2025-06-01T11:59:55Z'
        transactionHash:
          type: string
          description: The transaction hash of the detected activity.
          example: '0xabc123def456789012345678901234567890abcdef1234567890abcdef123456'
        logIndex:
          type: string
          description: The log index within the transaction.
          example: '0'
        contractAddress:
          type: string
          description: The contract address that emitted the event.
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        eventName:
          type: string
          description: The name of the decoded contract event.
          example: Transfer
      additionalProperties: true
      required:
        - network
        - transactionHash
      example:
        network: base-mainnet
        blockNumber: '12345678'
        blockTimestamp: '2025-06-01T11:59:55Z'
        transactionHash: '0xabc123def456789012345678901234567890abcdef1234567890abcdef123456'
        logIndex: '0'
        contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        eventName: Transfer
    WalletActivityEventBase:
      type: object
      description: Common fields included in every wallet activity webhook event payload.
      properties:
        eventId:
          type: string
          format: uuid
          description: Unique identifier for this webhook event. Use this for idempotency.
          example: 123e4567-e89b-12d3-a456-426614174000
        timestamp:
          type: string
          format: date-time
          description: When this event occurred (ISO 8601 format).
          example: '2025-06-01T12:00:00Z'
        data:
          $ref: '#/components/schemas/OnchainActivityEventData'
      required:
        - eventId
        - timestamp
        - data
    WalletActivityDetectedEvent:
      x-event-type: wallet.activity.detected
      allOf:
        - $ref: '#/components/schemas/WalletActivityEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - wallet.activity.detected
              example: wallet.activity.detected
          required:
            - eventType
    WalletActivityMultiEvent:
      x-event-type: wallet.activity.multi
      allOf:
        - $ref: '#/components/schemas/WalletActivityEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - wallet.activity.multi
              example: wallet.activity.multi
          required:
            - eventType
    WalletEvmTransactionCreatedPayload:
      type: object
      description: Payload for `wallet.transaction.created` on EVM networks. Includes the originating `address`.
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address that created the transaction.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: base
        created_at:
          type: string
          format: date-time
          description: When the transaction was created (ISO 8601 format).
          example: '2025-06-01T10:00:00Z'
      required:
        - address
        - network
        - created_at
    WalletApiKeyEventPayload:
      type: object
      description: Payload for API Key Wallet events. These events carry no end-user payload fields, so neither `user_id` nor `delegation_id` is present.
      not:
        anyOf:
          - required:
              - user_id
          - required:
              - delegation_id
    WalletSolanaTransactionCreatedPayload:
      type: object
      description: Payload for `wallet.transaction.created` on Solana. Solana transaction events do not include an `address`.
      properties:
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: solana
        created_at:
          type: string
          format: date-time
          description: When the transaction was created (ISO 8601 format).
          example: '2025-06-01T10:00:00Z'
      required:
        - network
        - created_at
      not:
        required:
          - address
    WalletUserEventPayload:
      type: object
      description: Payload for User Wallet events. The wallet is owned by an end user, identified by `user_id`. User Wallet actions do not include `delegation_id`.
      properties:
        user_id:
          type: string
          description: The user ID that owns the User Wallet.
          example: user_12345
      required:
        - user_id
      not:
        required:
          - delegation_id
    WalletDelegatedEventPayload:
      type: object
      description: Payload for delegated User Wallet events, where a User Wallet action was authorized via a delegation grant. Includes `user_id` and the `delegation_id` of the active grant.
      properties:
        user_id:
          type: string
          description: The user ID that owns the User Wallet.
          example: user_12345
        delegation_id:
          type: string
          description: The delegation grant ID used to authorize the action.
          example: delegation_af2937b0-9846-4fe7-bfe9-ccc22d935114
      required:
        - user_id
        - delegation_id
    WalletTransactionCreatedEvent:
      x-event-type: wallet.transaction.created
      description: 'Delivered when a transaction is created. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionCreatedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionCreatedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionCreatedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionCreatedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionCreatedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionCreatedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletEvmSigningPayload:
      type: object
      description: Payload for EVM wallet signing events. Carries the EVM signing `address` and timestamp; no network or transaction identifier.
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address that performed the signing.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        signed_at:
          type: string
          format: date-time
          description: When the signing occurred (ISO 8601 format).
          example: '2025-06-01T10:01:00Z'
      required:
        - address
        - signed_at
    WalletSolanaSigningPayload:
      type: object
      description: Payload for Solana wallet signing events. Carries the Solana signing `address` and timestamp; no network or transaction identifier.
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          description: The Solana wallet address that performed the signing.
          example: HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH
        signed_at:
          type: string
          format: date-time
          description: When the signing occurred (ISO 8601 format).
          example: '2025-06-01T10:01:00Z'
      required:
        - address
        - signed_at
    WalletTransactionSignedEvent:
      x-event-type: wallet.transaction.signed
      description: 'Delivered when a transaction is signed. Emitted for both EVM and Solana wallets. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletEvmTransactionBroadcastPayload:
      type: object
      description: Payload for `wallet.transaction.broadcast` on EVM networks. Includes `transaction_hash` and `address`.
      properties:
        transaction_hash:
          type: string
          description: The onchain transaction hash.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address that broadcast the transaction.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: base
        broadcast_at:
          type: string
          format: date-time
          description: When the transaction was broadcast (ISO 8601 format).
          example: '2025-06-01T10:02:00Z'
      required:
        - transaction_hash
        - address
        - network
        - broadcast_at
    WalletSolanaTransactionBroadcastPayload:
      type: object
      description: Payload for `wallet.transaction.broadcast` on Solana. Includes `transaction_signature` and omits `address`.
      properties:
        transaction_signature:
          type: string
          description: The Solana transaction signature.
          example: 5KtPn1LGuxhFiwjxErkxTb3BeHaGShVbirtk7vrWgEiaTaKKQSGkLmMX7vLBMA4oL9pGikhmL6K2Uf4VNBLEmmnF
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: solana
        broadcast_at:
          type: string
          format: date-time
          description: When the transaction was broadcast (ISO 8601 format).
          example: '2025-06-01T10:02:00Z'
      required:
        - transaction_signature
        - network
        - broadcast_at
    WalletTransactionBroadcastEvent:
      x-event-type: wallet.transaction.broadcast
      description: 'Delivered when a transaction is broadcast to the network. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionBroadcastPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionBroadcastPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionBroadcastPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionBroadcastPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionBroadcastPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionBroadcastPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletTransactionReplacedPayload:
      type: object
      description: Payload for `wallet.transaction.replaced`. EVM-only; Solana transactions are not replaceable.
      properties:
        transaction_hash:
          type: string
          description: The onchain transaction hash of the replaced transaction.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address whose transaction was replaced.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: base
        replaced_at:
          type: string
          format: date-time
          description: When the transaction was replaced (ISO 8601 format).
          example: '2025-06-01T10:03:00Z'
      required:
        - transaction_hash
        - address
        - network
        - replaced_at
    WalletTransactionReplacedEvent:
      x-event-type: wallet.transaction.replaced
      description: 'Delivered when a pending transaction is replaced (e.g. a fee bump). EVM-only. The payload is one of three EVM wallet-type variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing).'
      oneOf:
        - title: API Key Wallet
          allOf:
            - $ref: '#/components/schemas/WalletTransactionReplacedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet
          allOf:
            - $ref: '#/components/schemas/WalletTransactionReplacedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing)
          allOf:
            - $ref: '#/components/schemas/WalletTransactionReplacedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletTransactionPendingPayload:
      type: object
      description: Payload for `wallet.transaction.pending`. EVM-only. EIP-1559 fee fields are included.
      properties:
        transaction_hash:
          type: string
          description: The onchain transaction hash.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address whose transaction is pending.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: base
        pending_since:
          type: string
          format: date-time
          description: When the transaction entered the pending state (ISO 8601 format).
          example: '2025-06-01T10:04:00Z'
        max_fee_per_gas:
          type: string
          description: EIP-1559 max fee per gas in wei.
          example: '30000000000'
        max_priority_fee_per_gas:
          type: string
          description: EIP-1559 max priority fee per gas in wei.
          example: '1500000000'
      required:
        - transaction_hash
        - address
        - network
        - pending_since
        - max_fee_per_gas
        - max_priority_fee_per_gas
    WalletTransactionPendingEvent:
      x-event-type: wallet.transaction.pending
      description: 'Delivered when a transaction enters the pending state. EVM-only. The payload is one of three EVM wallet-type variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing).'
      oneOf:
        - title: API Key Wallet
          allOf:
            - $ref: '#/components/schemas/WalletTransactionPendingPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet
          allOf:
            - $ref: '#/components/schemas/WalletTransactionPendingPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing)
          allOf:
            - $ref: '#/components/schemas/WalletTransactionPendingPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletEvmTransactionConfirmedPayload:
      type: object
      description: Payload for `wallet.transaction.confirmed` on EVM networks. Includes `transaction_hash` and `address`.
      properties:
        transaction_hash:
          type: string
          description: The onchain transaction hash.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address that submitted the transaction.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: base
        confirmed_at:
          type: string
          format: date-time
          description: When the transaction was confirmed (ISO 8601 format).
          example: '2025-06-01T10:05:00Z'
      required:
        - transaction_hash
        - address
        - network
        - confirmed_at
    WalletSolanaTransactionConfirmedPayload:
      type: object
      description: Payload for `wallet.transaction.confirmed` on Solana. Includes `transaction_signature` and omits `address`.
      properties:
        transaction_signature:
          type: string
          description: The Solana transaction signature.
          example: 5KtPn1LGuxhFiwjxErkxTb3BeHaGShVbirtk7vrWgEiaTaKKQSGkLmMX7vLBMA4oL9pGikhmL6K2Uf4VNBLEmmnF
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: solana
        confirmed_at:
          type: string
          format: date-time
          description: When the transaction was confirmed (ISO 8601 format).
          example: '2025-06-01T10:05:00Z'
      required:
        - transaction_signature
        - network
        - confirmed_at
    WalletTransactionConfirmedEvent:
      x-event-type: wallet.transaction.confirmed
      description: 'Delivered when a transaction is confirmed onchain. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionConfirmedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionConfirmedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionConfirmedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionConfirmedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionConfirmedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionConfirmedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletEvmTransactionFailedPayload:
      type: object
      description: Payload for `wallet.transaction.failed` on EVM networks. Includes `transaction_hash` and `address`.
      properties:
        transaction_hash:
          type: string
          description: The onchain transaction hash.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        address:
          allOf:
            - $ref: '#/components/schemas/BlockchainAddress'
          pattern: ^0x[0-9a-fA-F]{40}$
          description: The EVM wallet address that submitted the transaction.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: base
        failed_at:
          type: string
          format: date-time
          description: When the transaction failed (ISO 8601 format).
          example: '2025-06-01T10:06:00Z'
      required:
        - transaction_hash
        - address
        - network
        - failed_at
    WalletSolanaTransactionFailedPayload:
      type: object
      description: Payload for `wallet.transaction.failed` on Solana. Includes `transaction_signature` and omits `address`.
      properties:
        transaction_signature:
          type: string
          description: The Solana transaction signature.
          example: 5KtPn1LGuxhFiwjxErkxTb3BeHaGShVbirtk7vrWgEiaTaKKQSGkLmMX7vLBMA4oL9pGikhmL6K2Uf4VNBLEmmnF
        network:
          allOf:
            - $ref: '#/components/schemas/Network'
          description: The blockchain network identifier.
          example: solana
        failed_at:
          type: string
          format: date-time
          description: When the transaction failed (ISO 8601 format).
          example: '2025-06-01T10:06:00Z'
      required:
        - transaction_signature
        - network
        - failed_at
    WalletTransactionFailedEvent:
      x-event-type: wallet.transaction.failed
      description: 'Delivered when a transaction fails. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionFailedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionFailedPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionFailedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionFailedPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmTransactionFailedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaTransactionFailedPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletDelegationCreatedEvent:
      type: object
      x-event-type: wallet.delegation.created
      description: Delivered when a delegation grant is created for a User Wallet.
      properties:
        delegation_id:
          type: string
          description: The unique identifier for the delegation grant.
          example: delegation_af2937b0-9846-4fe7-bfe9-ccc22d935114
        user_id:
          type: string
          description: The user ID that owns the delegation.
          example: user_12345
        expires_at:
          type: string
          format: date-time
          description: When the delegation expires (ISO 8601 format).
          example: '2025-07-01T10:00:00Z'
        created_at:
          type: string
          format: date-time
          description: When the delegation was created (ISO 8601 format).
          example: '2025-06-01T10:00:00Z'
      required:
        - delegation_id
        - user_id
        - expires_at
        - created_at
      example:
        delegation_id: delegation_af2937b0-9846-4fe7-bfe9-ccc22d935114
        user_id: user_12345
        expires_at: '2025-07-01T10:00:00Z'
        created_at: '2025-06-01T10:00:00Z'
    WalletDelegationRevokedEvent:
      type: object
      x-event-type: wallet.delegation.revoked
      description: Delivered when a delegation grant is revoked.
      properties:
        delegation_id:
          type: string
          description: The unique identifier for the delegation grant.
          example: delegation_af2937b0-9846-4fe7-bfe9-ccc22d935114
        user_id:
          type: string
          description: The user ID that owns the delegation.
          example: user_12345
        revoked_at:
          type: string
          format: date-time
          description: When the delegation was revoked (ISO 8601 format).
          example: '2025-06-01T11:00:00Z'
      required:
        - delegation_id
        - user_id
        - revoked_at
      example:
        delegation_id: delegation_af2937b0-9846-4fe7-bfe9-ccc22d935114
        user_id: user_12345
        revoked_at: '2025-06-01T11:00:00Z'
    WalletTypedDataSignedEvent:
      x-event-type: wallet.typed_data.signed
      description: 'Delivered when EIP-712 typed data is signed. EVM-only. Uses the EVM signing payload. The payload is one of three EVM wallet-type variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing).'
      oneOf:
        - title: API Key Wallet
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletMessageSignedEvent:
      x-event-type: wallet.message.signed
      description: 'Delivered when a message is signed. Emitted for both EVM and Solana wallets. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    WalletHashSignedEvent:
      x-event-type: wallet.hash.signed
      description: 'Delivered when a raw hash is signed. Emitted for both EVM and Solana wallets. The payload is one of six variants: API Key Wallet, User Wallet, or User Wallet (Delegated Signing), each delivered as an EVM or Solana variant.'
      oneOf:
        - title: API Key Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: API Key Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletApiKeyEventPayload'
        - title: User Wallet (EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletUserEventPayload'
        - title: User Wallet (Delegated Signing, EVM)
          allOf:
            - $ref: '#/components/schemas/WalletEvmSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
        - title: User Wallet (Delegated Signing, Solana)
          allOf:
            - $ref: '#/components/schemas/WalletSolanaSigningPayload'
            - $ref: '#/components/schemas/WalletDelegatedEventPayload'
    PaymentsTransfersEventBase:
      type: object
      description: Common envelope fields included in every payments transfers webhook event payload.
      properties:
        eventID:
          type: string
          format: uuid
          description: Unique identifier for this webhook event. Use this for idempotency.
          example: 123e4567-e89b-12d3-a456-426614174000
        eventType:
          type: string
          description: The type of webhook event.
          example: payments.transfers.completed
        timestamp:
          type: string
          format: date-time
          description: The UTC ISO 8601 timestamp at which the underlying state change occurred, not the time at which this webhook was delivered.
          example: '2026-01-01T00:05:00Z'
        data:
          $ref: '#/components/schemas/Transfer'
      required:
        - eventID
        - eventType
        - timestamp
        - data
    PaymentsTransfersQuotedEvent:
      x-event-type: payments.transfers.quoted
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.quoted
              example: payments.transfers.quoted
          required:
            - eventType
    PaymentsTransfersProcessingEvent:
      x-event-type: payments.transfers.processing
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.processing
              example: payments.transfers.processing
          required:
            - eventType
    PaymentsTransfersCompletedEvent:
      x-event-type: payments.transfers.completed
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.completed
              example: payments.transfers.completed
          required:
            - eventType
    PaymentsTransfersFailedEvent:
      x-event-type: payments.transfers.failed
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.failed
              example: payments.transfers.failed
          required:
            - eventType
    PaymentsTransfersExpiredEvent:
      x-event-type: payments.transfers.expired
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.expired
              example: payments.transfers.expired
          required:
            - eventType
    PaymentsTransfersTravelRuleIncompleteEvent:
      x-event-type: payments.transfers.travel_rule_incomplete
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.travel_rule_incomplete
              example: payments.transfers.travel_rule_incomplete
          required:
            - eventType
    PaymentsTransfersTravelRuleCompletedEvent:
      x-event-type: payments.transfers.travel_rule_completed
      allOf:
        - $ref: '#/components/schemas/PaymentsTransfersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - payments.transfers.travel_rule_completed
              example: payments.transfers.travel_rule_completed
          required:
            - eventType
    MoneyAmount:
      type: object
      description: A monetary amount with currency.
      properties:
        currency:
          type: string
          description: Currency code (e.g., "USD", "USDC", "ETH").
          example: USD
        value:
          type: string
          description: The amount as a string.
          example: '100.00'
      required:
        - currency
        - value
      example:
        currency: USD
        value: '5.00'
    OnrampTransactionPayload:
      type: object
      description: Webhook payload for standard onramp transactions (guest checkout and authed flow). Serialized from the OnrampTransaction proto via protojson with eventType appended.
      properties:
        eventType:
          type: string
          description: The webhook event type.
          example: onramp.transaction.updated
        transactionId:
          type: string
          description: Unique transaction identifier.
          example: 1f087a54-ff1f-62e8-9f85-aa77ac0499a5
        status:
          type: string
          description: Current status of the transaction.
          enum:
            - ONRAMP_TRANSACTION_STATUS_UNSPECIFIED
            - ONRAMP_TRANSACTION_STATUS_CREATED
            - ONRAMP_TRANSACTION_STATUS_IN_PROGRESS
            - ONRAMP_TRANSACTION_STATUS_SUCCESS
            - ONRAMP_TRANSACTION_STATUS_FAILED
            - ONRAMP_TRANSACTION_STATUS_AWAITING_AUTH
            - ONRAMP_TRANSACTION_STATUS_AWAITING_PAYMENT
          example: ONRAMP_TRANSACTION_STATUS_IN_PROGRESS
        purchaseCurrency:
          type: string
          description: The crypto currency purchased (e.g., "USDC", "ETH").
          example: USDC
        purchaseNetwork:
          type: string
          description: The blockchain network for the purchase (e.g., "ethereum", "base").
          example: ethereum
        purchaseAmount:
          $ref: '#/components/schemas/MoneyAmount'
        paymentTotal:
          $ref: '#/components/schemas/MoneyAmount'
        paymentTotalUsd:
          $ref: '#/components/schemas/MoneyAmount'
        paymentSubtotal:
          $ref: '#/components/schemas/MoneyAmount'
        coinbaseFee:
          $ref: '#/components/schemas/MoneyAmount'
        networkFee:
          $ref: '#/components/schemas/MoneyAmount'
        exchangeRate:
          $ref: '#/components/schemas/MoneyAmount'
        txHash:
          type: string
          description: The onchain transaction hash of the send (0x-prefixed for EVM).
          example: 0x
        createdAt:
          type: string
          format: date-time
          description: When the transaction was created.
          example: '2025-09-02T02:34:13Z'
        completedAt:
          type: string
          format: date-time
          description: When the transaction completed (uses send_started_at for early success).
          example: '0001-01-01T00:00:00Z'
        country:
          type: string
          description: The user's country code.
          example: US
        userId:
          type: string
          description: Hashed user identifier (entity hash for guest, user ID for authed).
          example: 4132b63ee21128686458155b28570289
        paymentMethod:
          type: string
          description: The payment method used.
          enum:
            - UNSPECIFIED
            - CARD
            - ACH_BANK_ACCOUNT
            - APPLE_PAY
            - FIAT_WALLET
            - CRYPTO_ACCOUNT
            - GUEST_CHECKOUT_CARD
            - PAYPAL
            - RTP
            - GUEST_CHECKOUT_APPLE_PAY
            - GUEST_CHECKOUT_GOOGLE_PAY
          example: CARD
        walletAddress:
          type: string
          description: The destination wallet address.
          example: '0xe0512E358C347cc2b1A42d057065CE642068b7Ba'
        type:
          type: string
          description: The type of onramp transaction.
          enum:
            - ONRAMP_TRANSACTION_TYPE_UNSPECIFIED
            - ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND
            - ONRAMP_TRANSACTION_TYPE_SEND
          example: ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND
        userType:
          type: string
          description: Whether the user is authed or guest.
          enum:
            - USER_TYPE_UNSPECIFIED
            - USER_TYPE_AUTHED
            - USER_TYPE_GUEST
          example: USER_TYPE_GUEST
        partnerUserRef:
          type: string
          description: The partnerUserId provided when initializing the onramp session.
          example: example_user_ref
        contractAddress:
          type: string
          description: The token contract address (populated when asset metadata is available).
          example: ''
        failureReason:
          type: string
          description: The reason for failure (if applicable).
          enum:
            - FAILURE_REASON_UNSPECIFIED
            - FAILURE_REASON_BUY_FAILED
            - FAILURE_REASON_SEND_FAILED
          example: FAILURE_REASON_UNSPECIFIED
        endPartnerName:
          type: string
          description: The name of the developer app.
          example: ''
        errorCode:
          type: string
          description: Error code for the transaction failure (if applicable).
          example: ERROR_CODE_UNSPECIFIED
      required:
        - eventType
        - transactionId
        - status
    OrderFee:
      type: object
      description: A fee associated with a Headless Onramp API order.
      properties:
        feeType:
          type: string
          description: The type of fee.
          enum:
            - FEE_TYPE_UNSPECIFIED
            - FEE_TYPE_NETWORK
            - FEE_TYPE_EXCHANGE
          example: FEE_TYPE_NETWORK
        feeAmount:
          type: string
          description: The amount of the fee.
          example: '0.5'
        feeCurrency:
          type: string
          description: The currency of the fee.
          example: USD
    OnrampOrderPayload:
      type: object
      description: Webhook payload for Headless Onramp API orders (Apple Pay / Google Pay). Serialized from the OnrampOrder proto via protojson with eventType appended.
      properties:
        eventType:
          type: string
          description: The webhook event type.
          example: onramp.transaction.success
        orderId:
          type: string
          format: uuid
          description: Unique order identifier.
          example: 123e4567-e89b-12d3-a456-426614174000
        paymentTotal:
          type: string
          description: The total fiat amount paid.
          example: '100.75'
        paymentSubtotal:
          type: string
          description: The fiat amount converted to crypto (excluding fees).
          example: '100'
        paymentCurrency:
          type: string
          description: The fiat currency used for payment.
          example: USD
        paymentMethod:
          type: string
          description: The payment method used.
          enum:
            - UNSPECIFIED
            - CARD
            - ACH_BANK_ACCOUNT
            - APPLE_PAY
            - FIAT_WALLET
            - CRYPTO_ACCOUNT
            - GUEST_CHECKOUT_CARD
            - PAYPAL
            - RTP
            - GUEST_CHECKOUT_APPLE_PAY
            - GUEST_CHECKOUT_GOOGLE_PAY
          example: GUEST_CHECKOUT_APPLE_PAY
        purchaseAmount:
          type: string
          description: The amount of crypto purchased.
          example: '100.000000'
        purchaseCurrency:
          type: string
          description: The crypto currency purchased.
          example: USDC
        fees:
          type: array
          description: Breakdown of fees for the order.
          items:
            $ref: '#/components/schemas/OrderFee'
          example:
            - feeType: FEE_TYPE_NETWORK
              feeAmount: '0.5'
              feeCurrency: USD
            - feeType: FEE_TYPE_EXCHANGE
              feeAmount: '0.25'
              feeCurrency: USD
        exchangeRate:
          type: string
          description: The exchange rate used for conversion.
          example: '1'
        destinationAddress:
          type: string
          description: The destination wallet address.
          example: '0x1234567890abcdef1234567890abcdef12345678'
        destinationNetwork:
          type: string
          description: The blockchain network for delivery.
          example: base
        status:
          type: string
          description: The status of the order.
          enum:
            - ONRAMP_ORDER_STATUS_UNSPECIFIED
            - ONRAMP_ORDER_STATUS_PENDING_AUTH
            - ONRAMP_ORDER_STATUS_PENDING_VERIFICATION
            - ONRAMP_ORDER_STATUS_PENDING_PAYMENT
            - ONRAMP_ORDER_STATUS_PROCESSING
            - ONRAMP_ORDER_STATUS_COMPLETED
            - ONRAMP_ORDER_STATUS_FAILED
          example: ONRAMP_ORDER_STATUS_COMPLETED
        txHash:
          type: string
          description: The onchain transaction hash (available once crypto is sent).
          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
        createdAt:
          type: string
          format: date-time
          description: When the order was created.
          example: '2025-09-10T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the order was last updated.
          example: '2025-09-10T10:35:00Z'
        partnerUserRef:
          type: string
          description: The partner user reference ID.
          example: example_user_ref
      required:
        - eventType
        - orderId
        - status
    OnrampTransactionEvent:
      description: Webhook payload for all onramp transaction events (created, updated, success, failed). Shape depends on transaction type — standard flow (guest checkout / authorized) uses OnrampTransactionPayload, Headless API (Apple Pay / Google Pay) uses OnrampOrderPayload. Distinguish by presence of `orderId` (Headless) vs `transactionId` (standard).
      oneOf:
        - $ref: '#/components/schemas/OnrampTransactionPayload'
        - $ref: '#/components/schemas/OnrampOrderPayload'
    OnrampTransactionCreatedEvent:
      x-event-type: onramp.transaction.created
      allOf:
        - $ref: '#/components/schemas/OnrampTransactionEvent'
    OnrampTransactionUpdatedEvent:
      x-event-type: onramp.transaction.updated
      allOf:
        - $ref: '#/components/schemas/OnrampTransactionEvent'
    OnrampTransactionSuccessEvent:
      x-event-type: onramp.transaction.success
      allOf:
        - $ref: '#/components/schemas/OnrampTransactionEvent'
    OnrampTransactionFailedEvent:
      x-event-type: onramp.transaction.failed
      allOf:
        - $ref: '#/components/schemas/OnrampTransactionEvent'
    OfframpTransactionPayload:
      type: object
      description: Webhook payload for offramp transactions. Serialized from the OfframpTransaction proto via protojson with eventType appended.
      properties:
        eventType:
          type: string
          description: The webhook event type.
          example: offramp.transaction.updated
        transactionId:
          type: string
          description: Unique transaction identifier.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          description: Current status of the offramp transaction.
          enum:
            - TRANSACTION_STATUS_UNSPECIFIED
            - TRANSACTION_STATUS_CREATED
            - TRANSACTION_STATUS_EXPIRED
            - TRANSACTION_STATUS_STARTED
            - TRANSACTION_STATUS_SUCCESS
            - TRANSACTION_STATUS_FAILED
          example: TRANSACTION_STATUS_STARTED
        asset:
          type: string
          description: The crypto currency being sold (e.g., "ETH", "USDC").
          example: ETH
        network:
          type: string
          description: The blockchain network (e.g., "ethereum", "base").
          example: ethereum
        sellAmount:
          $ref: '#/components/schemas/MoneyAmount'
        total:
          $ref: '#/components/schemas/MoneyAmount'
        minimumTotal:
          $ref: '#/components/schemas/MoneyAmount'
        subtotal:
          $ref: '#/components/schemas/MoneyAmount'
        coinbaseFee:
          $ref: '#/components/schemas/MoneyAmount'
        exchangeRate:
          $ref: '#/components/schemas/MoneyAmount'
        unitPrice:
          $ref: '#/components/schemas/MoneyAmount'
        fromAddress:
          type: string
          description: The address crypto was received from.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        toAddress:
          type: string
          description: The address crypto was sent to (Coinbase deposit address).
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        createdAt:
          type: string
          format: date-time
          description: When the transaction was created.
          example: '2025-09-02T02:34:13Z'
        updatedAt:
          type: string
          format: date-time
          description: When the transaction was last updated.
          example: '2025-09-02T02:40:00Z'
        txHash:
          type: string
          description: The onchain transaction hash of the crypto send.
          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
        redirectUrl:
          type: string
          description: The URL the user was redirected to after confirming the offramp.
          example: https://partner.com/offramp/complete
        paymentMethod:
          type: string
          description: The payment method type used for cashout.
          enum:
            - UNSPECIFIED
            - CARD
            - ACH_BANK_ACCOUNT
            - APPLE_PAY
            - FIAT_WALLET
            - CRYPTO_ACCOUNT
            - GUEST_CHECKOUT_CARD
            - PAYPAL
            - RTP
            - GUEST_CHECKOUT_APPLE_PAY
            - GUEST_CHECKOUT_GOOGLE_PAY
          example: ACH_BANK_ACCOUNT
        partnerUserRef:
          type: string
          description: The partnerUserId provided when initializing the offramp session.
          example: example_user_ref
      required:
        - eventType
        - transactionId
        - status
    OfframpTransactionCreatedEvent:
      x-event-type: offramp.transaction.created
      allOf:
        - $ref: '#/components/schemas/OfframpTransactionPayload'
    OfframpTransactionUpdatedEvent:
      x-event-type: offramp.transaction.updated
      allOf:
        - $ref: '#/components/schemas/OfframpTransactionPayload'
    OfframpTransactionSuccessEvent:
      x-event-type: offramp.transaction.success
      allOf:
        - $ref: '#/components/schemas/OfframpTransactionPayload'
    OfframpTransactionFailedEvent:
      x-event-type: offramp.transaction.failed
      allOf:
        - $ref: '#/components/schemas/OfframpTransactionPayload'
    PaymentSessionSummary:
      type: object
      description: A summary of the payment session included in webhook payloads. Contains the session identity, amount, asset, payer and recipient information, execution behavior, expiry deadlines, current status, running balance totals, and any metadata originally provided when the session was created.
      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
        source:
          allOf:
            - $ref: '#/components/schemas/PaymentSessionSource'
          description: The payer's address and network. Set after a successful authorization. Not present before authorization.
          example:
            address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
            network: base
            asset: usdc
        target:
          allOf:
            - $ref: '#/components/schemas/PaymentSessionTarget'
          description: The recipient of the payment.
          example:
            address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            network: base
        autoCapture:
          type: boolean
          description: When true, a capture is automatically created after a successful authorization.
          example: false
        expiries:
          allOf:
            - $ref: '#/components/schemas/PaymentExpiries'
          description: Deadline timestamps for authorization, capture, and refund windows.
          example:
            authorizationExpiresAt: '2025-12-31T23:59:59.000Z'
            captureExpiresAt: '2026-01-15T23:59:59.000Z'
            refundExpiresAt: '2026-02-15T23:59:59.000Z'
        status:
          allOf:
            - $ref: '#/components/schemas/PaymentSessionStatus'
          description: The current status of the payment session at the time the event was emitted.
          example: authorization_succeeded
        balances:
          allOf:
            - $ref: '#/components/schemas/PaymentSessionBalances'
          description: Running balance totals for the payment session at the time the event was emitted.
          example:
            capturable: '1.00'
            captured: '0'
            refundable: '0'
            refunded: '0'
        externalReferenceId:
          type: string
          maxLength: 256
          description: A merchant-provided internal identifier for this payment session, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.
          example: merchant-order-abc123
        customerDisplay:
          $ref: '#/components/schemas/CustomerDisplay'
        metadata:
          $ref: '#/components/schemas/Metadata'
        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'
      required:
        - paymentSessionId
        - entityId
        - amount
        - asset
        - target
        - autoCapture
        - expiries
        - status
        - balances
        - createdAt
        - updatedAt
      example:
        paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
        entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
        amount: '1.00'
        asset: usdc
        source:
          address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
          network: base
          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: authorization_succeeded
        balances:
          capturable: '1.00'
          captured: '0'
          refundable: '0'
          refunded: '0'
        externalReferenceId: merchant-order-abc123
        customerDisplay:
          merchantName: Acme Store
          displayAmount:
            amount: '1.37'
            currency: cad
        metadata:
          customer_id: cust_12345
          order_reference: order-67890
        createdAt: '2025-06-15T12:00:00.000Z'
        updatedAt: '2025-06-15T12:01:00.000Z'
    PaymentSessionEventData:
      type: object
      description: The data payload for a payment session webhook event. Always contains the `paymentSession` summary reflecting the session's current state. When the event was triggered by an action (authorization, capture, void, or refund), the corresponding optional field is present with the action details. For session-level events (created, canceled) no action field is included — the `paymentSession.status` value is sufficient.
      properties:
        paymentSession:
          $ref: '#/components/schemas/PaymentSessionSummary'
        authorization:
          type: object
          description: Present when the event was triggered by an authorization status transition (`pending`, `succeeded`, or `failed`).
          properties:
            authorizationId:
              allOf:
                - $ref: '#/components/schemas/AuthorizationId'
              description: The unique identifier of the authorization.
              example: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status:
              allOf:
                - $ref: '#/components/schemas/PaymentActionStatus'
              description: The current status of the authorization.
              example: succeeded
            amount:
              type: string
              description: A decimal representation of the authorized amount, denominated in the session's `asset`.
              example: '1.00'
            error:
              allOf:
                - $ref: '#/components/schemas/PaymentError'
              description: Error details, present only when the authorization failed.
              example:
                code: insufficient_funds
                message: The payer does not have sufficient funds.
                occurredAt: '2025-06-15T12:01:00.000Z'
            onchainTransactions:
              type: array
              description: The onchain transactions associated with this authorization.
              items:
                $ref: '#/components/schemas/OnchainTransaction'
              example:
                - transactionHash: '0xabc123def456789012345678901234567890abcdef1234567890abcdef123456'
                  network: base
            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.
              example:
                address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
                network: base
                asset: usdc
            createdAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the authorization was created.
              example: '2025-06-15T12:00:30.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'
          required:
            - authorizationId
            - status
            - amount
            - createdAt
            - updatedAt
          example:
            authorizationId: authorization_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:00:30.000Z'
            updatedAt: '2025-06-15T12:01:00.000Z'
        capture:
          type: object
          description: Present when the event was triggered by a capture status transition (`pending`, `succeeded`, or `failed`).
          properties:
            captureId:
              allOf:
                - $ref: '#/components/schemas/CaptureId'
              description: The unique identifier of the capture.
              example: capture_93d980d2-95f2-55fe-b9d3-2bd340cf10be
            status:
              allOf:
                - $ref: '#/components/schemas/PaymentActionStatus'
              description: The current status of the capture.
              example: succeeded
            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:
              allOf:
                - $ref: '#/components/schemas/PaymentError'
              description: Error details, present only when the capture failed.
              example:
                code: capture_failed
                message: The capture could not be completed.
                occurredAt: '2025-06-15T12:05:00.000Z'
            onchainTransactions:
              type: array
              description: The onchain transactions associated with this capture.
              items:
                $ref: '#/components/schemas/OnchainTransaction'
              example:
                - transactionHash: '0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678'
                  network: base
            metadata:
              $ref: '#/components/schemas/Metadata'
            createdAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the capture was created.
              example: '2025-06-15T12:04:30.000Z'
            updatedAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the capture was last updated.
              example: '2025-06-15T12:05:00.000Z'
          required:
            - captureId
            - status
            - amount
            - finalCapture
            - createdAt
            - updatedAt
          example:
            captureId: capture_93d980d2-95f2-55fe-b9d3-2bd340cf10be
            status: succeeded
            amount: '1.00'
            finalCapture: true
            onchainTransactions:
              - transactionHash: '0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678'
                network: base
            createdAt: '2025-06-15T12:04:30.000Z'
            updatedAt: '2025-06-15T12:05:00.000Z'
        void:
          type: object
          description: Present when the event was triggered by a void status transition (`pending`, `succeeded`, or `failed`).
          properties:
            voidId:
              allOf:
                - $ref: '#/components/schemas/VoidId'
              description: The unique identifier of the void.
              example: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status:
              allOf:
                - $ref: '#/components/schemas/PaymentActionStatus'
              description: The current status of the void.
              example: succeeded
            amount:
              type: string
              description: A decimal representation of the voided amount, denominated in the session's `asset`.
              example: '1.00'
            error:
              allOf:
                - $ref: '#/components/schemas/PaymentError'
              description: Error details, present only when the void failed.
              example:
                code: void_failed
                message: The void could not be completed.
                occurredAt: '2025-06-15T12:10:00.000Z'
            onchainTransactions:
              type: array
              description: The onchain transactions associated with this void.
              items:
                $ref: '#/components/schemas/OnchainTransaction'
              example:
                - transactionHash: '0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12'
                  network: base
            metadata:
              $ref: '#/components/schemas/Metadata'
            createdAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the void was created.
              example: '2025-06-15T12:09:30.000Z'
            updatedAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the void was last updated.
              example: '2025-06-15T12:10:00.000Z'
          required:
            - voidId
            - status
            - amount
            - createdAt
            - updatedAt
          example:
            voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: succeeded
            amount: '1.00'
            onchainTransactions:
              - transactionHash: '0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12'
                network: base
            createdAt: '2025-06-15T12:09:30.000Z'
            updatedAt: '2025-06-15T12:10:00.000Z'
        refund:
          type: object
          description: Present when the event was triggered by a refund status transition (`pending`, `succeeded`, or `failed`).
          properties:
            refundId:
              allOf:
                - $ref: '#/components/schemas/RefundId'
              description: The unique identifier of the refund.
              example: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status:
              allOf:
                - $ref: '#/components/schemas/PaymentActionStatus'
              description: The current status of the refund.
              example: succeeded
            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, if provided when the refund was created.
              example: Customer returned the item.
            error:
              allOf:
                - $ref: '#/components/schemas/PaymentError'
              description: Error details, present only when the refund failed.
              example:
                code: refund_failed
                message: The refund could not be completed.
                occurredAt: '2025-06-15T12:15:00.000Z'
            onchainTransactions:
              type: array
              description: The onchain transactions associated with this refund.
              items:
                $ref: '#/components/schemas/OnchainTransaction'
              example:
                - transactionHash: '0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234'
                  network: base
            metadata:
              $ref: '#/components/schemas/Metadata'
            createdAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the refund was created.
              example: '2025-06-15T12:14:30.000Z'
            updatedAt:
              type: string
              format: date-time
              description: The UTC ISO 8601 timestamp at which the refund was last updated.
              example: '2025-06-15T12:15:00.000Z'
          required:
            - refundId
            - status
            - amount
            - createdAt
            - updatedAt
          example:
            refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: succeeded
            amount: '0.50'
            reason: Customer returned the item.
            onchainTransactions:
              - transactionHash: '0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234'
                network: base
            createdAt: '2025-06-15T12:14:30.000Z'
            updatedAt: '2025-06-15T12:15:00.000Z'
      required:
        - paymentSession
      example:
        paymentSession:
          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'
          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'
    PaymentSessionEventBase:
      type: object
      description: Common fields included in every PaymentSessionEvent payload.
      properties:
        eventId:
          type: string
          format: uuid
          description: Unique identifier for this webhook event. Use this for idempotency.
          example: 123e4567-e89b-12d3-a456-426614174000
        timestamp:
          type: string
          format: date-time
          description: When this event occurred (ISO 8601 format).
          example: '2025-06-01T12:00:00Z'
        data:
          $ref: '#/components/schemas/PaymentSessionEventData'
      required:
        - eventId
        - timestamp
        - data
    AcceptancePaymentSessionCreatedEvent:
      x-event-type: acceptance.payment_session.created
      example:
        eventType: acceptance.payment_session.created
        eventId: 123e4567-e89b-12d3-a456-426614174000
        timestamp: '2025-06-15T12:00:00Z'
        data:
          paymentSession:
            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'
            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'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.created
              example: acceptance.payment_session.created
          required:
            - eventType
    AcceptancePaymentSessionCanceledEvent:
      x-event-type: acceptance.payment_session.canceled
      example:
        eventType: acceptance.payment_session.canceled
        eventId: 234f5678-f90c-23e4-b567-537725285111
        timestamp: '2025-06-15T12:05:00Z'
        data:
          paymentSession:
            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: canceled
            balances:
              capturable: '0'
              captured: '0'
              refundable: '0'
              refunded: '0'
            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'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.canceled
              example: acceptance.payment_session.canceled
          required:
            - eventType
    AcceptancePaymentSessionAuthorizationPendingEvent:
      x-event-type: acceptance.payment_session.authorization_pending
      example:
        eventType: acceptance.payment_session.authorization_pending
        eventId: 345g6789-g01d-34f5-c678-648836396222
        timestamp: '2025-06-15T12:01:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: authorization_pending
            balances:
              capturable: '0'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:01:00.000Z'
          authorization:
            authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: pending
            amount: '1.00'
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              asset: usdc
            createdAt: '2025-06-15T12:01:00.000Z'
            updatedAt: '2025-06-15T12:01:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.authorization_pending
              example: acceptance.payment_session.authorization_pending
          required:
            - eventType
    AcceptancePaymentSessionAuthorizationSucceededEvent:
      x-event-type: acceptance.payment_session.authorization_succeeded
      example:
        eventType: acceptance.payment_session.authorization_succeeded
        eventId: 456h7890-h12e-45g6-d789-759947407333
        timestamp: '2025-06-15T12:02:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: authorization_succeeded
            balances:
              capturable: '1.00'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:02:00.000Z'
          authorization:
            authorizationId: authorization_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'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.authorization_succeeded
              example: acceptance.payment_session.authorization_succeeded
          required:
            - eventType
    AcceptancePaymentSessionAuthorizationFailedEvent:
      x-event-type: acceptance.payment_session.authorization_failed
      example:
        eventType: acceptance.payment_session.authorization_failed
        eventId: 567i8901-i23f-56h7-e890-860058518444
        timestamp: '2025-06-15T12:02:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: authorization_failed
            balances:
              capturable: '0'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:02:00.000Z'
          authorization:
            authorizationId: authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: failed
            amount: '1.00'
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              asset: usdc
            error:
              code: insufficient_funds
              message: The payer does not have sufficient funds.
              occurredAt: '2025-06-15T12:02:00.000Z'
            createdAt: '2025-06-15T12:01:00.000Z'
            updatedAt: '2025-06-15T12:02:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.authorization_failed
              example: acceptance.payment_session.authorization_failed
          required:
            - eventType
    AcceptancePaymentSessionCapturePendingEvent:
      x-event-type: acceptance.payment_session.capture_pending
      example:
        eventType: acceptance.payment_session.capture_pending
        eventId: 678j9012-j34g-67i8-f901-971169629555
        timestamp: '2025-06-15T12:20:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: capture_pending
            balances:
              capturable: '1.00'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:20:00.000Z'
          capture:
            captureId: capture_93d980d2-95f2-55fe-b9d3-2bd340cf10be
            status: pending
            amount: '1.00'
            finalCapture: true
            createdAt: '2025-06-15T12:20:00.000Z'
            updatedAt: '2025-06-15T12:20:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.capture_pending
              example: acceptance.payment_session.capture_pending
          required:
            - eventType
    AcceptancePaymentSessionCaptureSucceededEvent:
      x-event-type: acceptance.payment_session.capture_succeeded
      example:
        eventType: acceptance.payment_session.capture_succeeded
        eventId: 789k0123-k45h-78j9-g012-082270730666
        timestamp: '2025-06-15T12:21:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: capture_succeeded
            balances:
              capturable: '0'
              captured: '1.00'
              refundable: '1.00'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:21:00.000Z'
          capture:
            captureId: capture_93d980d2-95f2-55fe-b9d3-2bd340cf10be
            status: succeeded
            amount: '1.00'
            finalCapture: true
            onchainTransactions:
              - transactionHash: '0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678'
                network: base
            createdAt: '2025-06-15T12:20:00.000Z'
            updatedAt: '2025-06-15T12:21:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.capture_succeeded
              example: acceptance.payment_session.capture_succeeded
          required:
            - eventType
    AcceptancePaymentSessionCaptureFailedEvent:
      x-event-type: acceptance.payment_session.capture_failed
      example:
        eventType: acceptance.payment_session.capture_failed
        eventId: 890l1234-l56i-89k0-h123-193381841777
        timestamp: '2025-06-15T12:21:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: capture_failed
            balances:
              capturable: '1.00'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:21:00.000Z'
          capture:
            captureId: capture_93d980d2-95f2-55fe-b9d3-2bd340cf10be
            status: failed
            amount: '1.00'
            finalCapture: true
            error:
              code: capture_failed
              message: The capture could not be completed.
              occurredAt: '2025-06-15T12:21:00.000Z'
            createdAt: '2025-06-15T12:20:00.000Z'
            updatedAt: '2025-06-15T12:21:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.capture_failed
              example: acceptance.payment_session.capture_failed
          required:
            - eventType
    AcceptancePaymentSessionRefundPendingEvent:
      x-event-type: acceptance.payment_session.refund_pending
      example:
        eventType: acceptance.payment_session.refund_pending
        eventId: 901m2345-m67j-90l1-i234-204492952888
        timestamp: '2025-06-15T12:40:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: refund_pending
            balances:
              capturable: '0'
              captured: '1.00'
              refundable: '1.00'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:40:00.000Z'
          refund:
            refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: pending
            amount: '0.50'
            reason: Customer returned the item.
            createdAt: '2025-06-15T12:40:00.000Z'
            updatedAt: '2025-06-15T12:40:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.refund_pending
              example: acceptance.payment_session.refund_pending
          required:
            - eventType
    AcceptancePaymentSessionRefundSucceededEvent:
      x-event-type: acceptance.payment_session.refund_succeeded
      example:
        eventType: acceptance.payment_session.refund_succeeded
        eventId: 012n3456-n78k-01m2-j345-315503063999
        timestamp: '2025-06-15T12:41:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: refund_succeeded
            balances:
              capturable: '0'
              captured: '1.00'
              refundable: '0.50'
              refunded: '0.50'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:41:00.000Z'
          refund:
            refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: succeeded
            amount: '0.50'
            reason: Customer returned the item.
            onchainTransactions:
              - transactionHash: '0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234'
                network: base
            createdAt: '2025-06-15T12:40:00.000Z'
            updatedAt: '2025-06-15T12:41:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.refund_succeeded
              example: acceptance.payment_session.refund_succeeded
          required:
            - eventType
    AcceptancePaymentSessionRefundFailedEvent:
      x-event-type: acceptance.payment_session.refund_failed
      example:
        eventType: acceptance.payment_session.refund_failed
        eventId: 123o4567-o89l-12n3-k456-426614174000
        timestamp: '2025-06-15T12:41:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: refund_failed
            balances:
              capturable: '0'
              captured: '1.00'
              refundable: '1.00'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:41:00.000Z'
          refund:
            refundId: refund_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: failed
            amount: '0.50'
            reason: Customer returned the item.
            error:
              code: refund_failed
              message: The refund could not be completed.
              occurredAt: '2025-06-15T12:41:00.000Z'
            createdAt: '2025-06-15T12:40:00.000Z'
            updatedAt: '2025-06-15T12:41:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.refund_failed
              example: acceptance.payment_session.refund_failed
          required:
            - eventType
    AcceptancePaymentSessionVoidPendingEvent:
      x-event-type: acceptance.payment_session.void_pending
      example:
        eventType: acceptance.payment_session.void_pending
        eventId: 234p5678-p90m-23o4-l567-537725285111
        timestamp: '2025-06-15T12:30:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: void_pending
            balances:
              capturable: '1.00'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:30:00.000Z'
          void:
            voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: pending
            amount: '1.00'
            createdAt: '2025-06-15T12:30:00.000Z'
            updatedAt: '2025-06-15T12:30:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.void_pending
              example: acceptance.payment_session.void_pending
          required:
            - eventType
    AcceptancePaymentSessionVoidSucceededEvent:
      x-event-type: acceptance.payment_session.void_succeeded
      example:
        eventType: acceptance.payment_session.void_succeeded
        eventId: 345q6789-q01n-34p5-m678-648836396222
        timestamp: '2025-06-15T12:31:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: void_succeeded
            balances:
              capturable: '0'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:31:00.000Z'
          void:
            voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: succeeded
            amount: '1.00'
            onchainTransactions:
              - transactionHash: '0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12'
                network: base
            createdAt: '2025-06-15T12:30:00.000Z'
            updatedAt: '2025-06-15T12:31:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.void_succeeded
              example: acceptance.payment_session.void_succeeded
          required:
            - eventType
    AcceptancePaymentSessionVoidFailedEvent:
      x-event-type: acceptance.payment_session.void_failed
      example:
        eventType: acceptance.payment_session.void_failed
        eventId: 456r7890-r12o-45q6-n789-759947407333
        timestamp: '2025-06-15T12:31:00Z'
        data:
          paymentSession:
            paymentSessionId: paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            entityId: entity_af2937b0-9846-4fe7-bfe9-ccc22d935114
            amount: '1.00'
            asset: usdc
            source:
              address: '0xAbC1234567890aBcDeF1234567890AbCdEf123456'
              network: base
              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: void_failed
            balances:
              capturable: '1.00'
              captured: '0'
              refundable: '0'
              refunded: '0'
            externalReferenceId: merchant-order-abc123
            metadata:
              customer_id: cust_12345
              order_reference: order-67890
            createdAt: '2025-06-15T12:00:00.000Z'
            updatedAt: '2025-06-15T12:31:00.000Z'
          void:
            voidId: void_82c879c1-84e1-44ed-a8c2-1ac239cf09ad
            status: failed
            amount: '1.00'
            error:
              code: void_failed
              message: The void could not be completed.
              occurredAt: '2025-06-15T12:31:00.000Z'
            createdAt: '2025-06-15T12:30:00.000Z'
            updatedAt: '2025-06-15T12:31:00.000Z'
      allOf:
        - $ref: '#/components/schemas/PaymentSessionEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.payment_session.void_failed
              example: acceptance.payment_session.void_failed
          required:
            - eventType
    DisbursementEventBase:
      type: object
      description: Common fields included in every DisbursementEvent payload.
      properties:
        eventId:
          type: string
          format: uuid
          description: Unique identifier for this webhook event. Use this for idempotency.
          example: 123e4567-e89b-12d3-a456-426614174000
        timestamp:
          type: string
          format: date-time
          description: When this event occurred (ISO 8601 format).
          example: '2025-06-01T12:00:00Z'
        data:
          $ref: '#/components/schemas/Disbursement'
      required:
        - eventId
        - timestamp
        - data
    AcceptanceDisbursementPendingEvent:
      x-event-type: acceptance.disbursement.pending
      example:
        eventType: acceptance.disbursement.pending
        eventId: 123e4567-e89b-12d3-a456-426614174000
        timestamp: '2026-04-17T17:00:00Z'
        data:
          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
          createdAt: '2026-04-17T17:00:00.000Z'
          updatedAt: '2026-04-17T17:00:00.000Z'
      allOf:
        - $ref: '#/components/schemas/DisbursementEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.disbursement.pending
              example: acceptance.disbursement.pending
          required:
            - eventType
    AcceptanceDisbursementSucceededEvent:
      x-event-type: acceptance.disbursement.succeeded
      example:
        eventType: acceptance.disbursement.succeeded
        eventId: 234f5678-f90c-23e4-b567-537725285111
        timestamp: '2026-04-17T17:05:00Z'
        data:
          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
          onchainTransactions:
            - transactionHash: '0xabc123def456789012345678901234567890abcdef1234567890abcdef123456'
              network: base
          createdAt: '2026-04-17T17:00:00.000Z'
          updatedAt: '2026-04-17T17:05:00.000Z'
      allOf:
        - $ref: '#/components/schemas/DisbursementEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.disbursement.succeeded
              example: acceptance.disbursement.succeeded
          required:
            - eventType
    AcceptanceDisbursementFailedEvent:
      x-event-type: acceptance.disbursement.failed
      example:
        eventType: acceptance.disbursement.failed
        eventId: 345g6789-g01d-34f5-c678-648836396222
        timestamp: '2026-04-17T17:01:00Z'
        data:
          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: failed
          reason: Goodwill disbursement for delayed shipment.
          externalReferenceId: disbursement-2026-04-1234
          error:
            code: insufficient_funds
            message: The source account does not have sufficient funds.
            occurredAt: '2026-04-17T17:01:00.000Z'
          createdAt: '2026-04-17T17:00:00.000Z'
          updatedAt: '2026-04-17T17:01:00.000Z'
      allOf:
        - $ref: '#/components/schemas/DisbursementEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - acceptance.disbursement.failed
              example: acceptance.disbursement.failed
          required:
            - eventType
    CustomersEventBase:
      type: object
      description: Common envelope fields included in every Customers webhook event payload.
      properties:
        eventId:
          type: string
          format: uuid
          description: Unique identifier for this logical webhook event. Webhooks are delivered at least once, so your endpoint may receive duplicate deliveries for the same event. Use this `eventId` as the idempotency/deduplication key.
          example: 3a7f8b2e-1c4d-4e9a-b5f6-d8a2c0e7f194
        eventType:
          type: string
          description: The type of webhook event.
          example: customers.customer.deleted
        timestamp:
          type: string
          format: date-time
          description: The UTC ISO 8601 timestamp at which the underlying state change occurred, not the time at which this webhook was delivered.
          example: '2026-04-01T12:00:02Z'
      required:
        - eventId
        - eventType
        - timestamp
    CustomersCapabilityChangedEvent:
      x-event-type: customers.capability.changed
      allOf:
        - $ref: '#/components/schemas/CustomersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - customers.capability.changed
              example: customers.capability.changed
            data:
              type: object
              description: Payload body for the `customers.capability.changed` event. Emitted when the status of a capability changes. Several capabilities may change in a single event, with each change represented by a distinct entry in the `capabilities` array.
              properties:
                customerId:
                  allOf:
                    - $ref: '#/components/schemas/CustomerId'
                  description: The CDP Customer ID the event applies to.
                  example: customer_38d54acb-0868-431c-a88e-1ffcb62655eb
                capabilities:
                  type: array
                  description: The set of capabilities whose status changed in this event.
                  minItems: 1
                  items:
                    type: object
                    description: A single capability whose status changed. Carries only `{code, status}`.
                    properties:
                      code:
                        allOf:
                          - $ref: '#/components/schemas/CapabilityName'
                        description: The capability whose status changed.
                        example: custodyFiat
                      status:
                        allOf:
                          - $ref: '#/components/schemas/CapabilityStatus'
                        description: The new status of the capability after the change.
                        example: active
                    required:
                      - code
                      - status
                    example:
                      code: custodyFiat
                      status: active
                  example:
                    - code: custodyFiat
                      status: inactive
                    - code: custodyStablecoin
                      status: inactive
                    - code: transferFiat
                      status: inactive
              required:
                - customerId
                - capabilities
              example:
                customerId: customer_38d54acb-0868-431c-a88e-1ffcb62655eb
                capabilities:
                  - code: custodyFiat
                    status: active
          required:
            - eventType
            - data
    CustomersCustomerDeletedEvent:
      x-event-type: customers.customer.deleted
      allOf:
        - $ref: '#/components/schemas/CustomersEventBase'
        - type: object
          properties:
            eventType:
              type: string
              description: The type of webhook event.
              enum:
                - customers.customer.deleted
              example: customers.customer.deleted
            data:
              type: object
              description: Payload body for the `customers.customer.deleted` event. Emitted when the Customer record is deleted; this transition is terminal.
              properties:
                customerId:
                  allOf:
                    - $ref: '#/components/schemas/CustomerId'
                  description: The ID of the deleted Customer.
                  example: customer_38d54acb-0868-431c-a88e-1ffcb62655eb
              required:
                - customerId
              example:
                customerId: customer_38d54acb-0868-431c-a88e-1ffcb62655eb
          required:
            - eventType
            - data
  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.
    RateLimitExceeded:
      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.
    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.
    PaymentMethodRequiredError:
      description: A payment method is required to complete this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            payment_method_required:
              value:
                errorType: payment_method_required
                errorMessage: A valid payment method is required to complete this operation. Please add a payment method to your account at https://portal.cdp.coinbase.com.
    DelegationForbiddenError:
      description: The request was rejected due to a delegation issue. The errorType field indicates the specific reason.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                errorType: forbidden
                errorMessage: Unable to complete the requested signing or sending operation for this address.
            delegation_not_found:
              value:
                errorType: delegation_not_found
                errorMessage: Unable to complete this operation. No active delegation grant was found. Create a delegation for this operation and try again.
            delegation_expired:
              value:
                errorType: delegation_expired
                errorMessage: The delegation grant has expired. Create a new delegation grant and retry the request.
            delegation_revoked:
              value:
                errorType: delegation_revoked
                errorMessage: The delegation grant has been revoked. Please create a new delegation.
            delegation_not_authorized:
              value:
                errorType: delegation_not_authorized
                errorMessage: The delegation grant does not authorize this operation.
            delegation_not_enabled:
              value:
                errorType: delegation_not_enabled
                errorMessage: Delegated signing is not enabled for this project.
    AlreadyExistsError:
      description: The resource already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            idempotency_key_already_exists:
              value:
                errorType: already_exists
                errorMessage: Another request with the same idempotency key is currently processing.
    InvalidSQLQueryError:
      description: The underlying SQL string is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unsupported_query:
              value:
                errorType: invalid_sql_query
                errorMessage: INSERTs are not supported.
            invalid_sql:
              value:
                errorType: invalid_sql_query
                errorMessage: 'SQL syntax error: Invalid table name ''invalid_table''.'
            query_too_long:
              value:
                errorType: invalid_sql_query
                errorMessage: Query exceeds maximum length of 10,000 characters.
    ClientClosedRequestError:
      description: The client closed the connection before the server could send a response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            client_closed_request:
              value:
                errorType: client_closed_request
                errorMessage: The client closed the request before the server could send a response.
    TimedOutError:
      description: The request timed out.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            timed_out:
              value:
                errorType: timed_out
                errorMessage: The request timed out because the server did not respond in time.
    x402VerifyResponse:
      description: Successfully verified payment on the x402 protocol.
      content:
        application/json:
          schema:
            type: object
            properties:
              isValid:
                type: boolean
                description: Indicates whether the payment is valid.
                example: false
              invalidReason:
                $ref: '#/components/schemas/x402VerifyInvalidReason'
              invalidMessage:
                type: string
                description: The message describing the invalid reason.
                example: Insufficient funds
              payer:
                allOf:
                  - $ref: '#/components/schemas/BlockchainAddress'
                description: |-
                  The onchain address of the client that is paying for the resource.

                  For EVM networks, the payer will be a 0x-prefixed, checksum EVM address.

                  For Solana-based networks, the payer will be a base58-encoded Solana address.
                example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              extra:
                type: object
                description: Optional scheme-specific verify metadata returned by the facilitator.
                additionalProperties: true
                example: {}
            required:
              - isValid
              - payer
    x402VerifyInvalidError:
      description: Invalid payment verification on the x402 protocol.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/x402VerifyPaymentRejection'
          examples:
            invalid_verification:
              value:
                isValid: false
                invalidReason: insufficient_funds
                invalidMessage: Insufficient funds
                payer: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    x402SettleResponse:
      description: Successfully settled payment on the x402 protocol.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                description: Indicates whether the payment settlement is successful.
                example: false
              errorReason:
                $ref: '#/components/schemas/x402SettleErrorReason'
              errorMessage:
                type: string
                description: The message describing the error reason.
                example: Insufficient funds
              payer:
                allOf:
                  - $ref: '#/components/schemas/BlockchainAddress'
                description: |-
                  The onchain address of the client that is paying for the resource.

                  For EVM networks, the payer will be a 0x-prefixed, checksum EVM address.

                  For Solana-based networks, the payer will be a base58-encoded Solana address.
                example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              transaction:
                type: string
                description: |-
                  The transaction of the settlement.
                  For EVM networks, the transaction will be a 0x-prefixed, EVM transaction hash.
                  For Solana-based networks, the transaction will be a base58-encoded Solana signature.
                pattern: ^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{87,88})$
                example: '0x89c91c789e57059b17285e7ba1716a1f5ff4c5dace0ea5a5135f26158d0421b9'
              network:
                type: string
                description: The network where the settlement occurred.
                example: base
              amount:
                type: string
                description: The amount that was settled, in atomic units.
                example: '1000000'
              extra:
                type: object
                description: Optional scheme-specific success metadata returned by the facilitator.
                additionalProperties: true
                example:
                  chargedAmount: '1000000'
                  channelState:
                    channelId: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                    balance: '9000000'
                    totalClaimed: '1000000'
                    withdrawRequestedAt: 0
                    refundNonce: '0'
                  voucherState:
                    signedMaxClaimable: '1000000'
                    signature: '0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f134801234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b'
            required:
              - success
              - payer
              - transaction
              - network
    x402SettleError:
      description: Unsuccessful payment settlement on the x402 protocol.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/x402SettlePaymentRejection'
          examples:
            unsuccessful_settlement:
              value:
                success: false
                errorReason: insufficient_funds
                errorMessage: Insufficient funds
                payer: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
    x402SupportedPaymentKindsResponse:
      description: Successfully retrieved supported payment kinds for the x402 protocol.
      content:
        application/json:
          schema:
            type: object
            properties:
              kinds:
                type: array
                description: The list of supported payment kinds.
                items:
                  $ref: '#/components/schemas/x402SupportedPaymentKind'
                example:
                  - x402Version: 2
                    scheme: exact
                    network: eip155:8453
                  - x402Version: 2
                    scheme: exact
                    network: eip155:84532
                  - x402Version: 2
                    scheme: exact
                    network: eip155:137
                  - x402Version: 2
                    scheme: exact
                    network: eip155:42161
                  - x402Version: 2
                    scheme: exact
                    network: eip155:480
                  - x402Version: 2
                    scheme: exact
                    network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
                    extra:
                      feePayer: BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP
                  - x402Version: 2
                    scheme: exact
                    network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
                    extra:
                      feePayer: BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP
                  - x402Version: 2
                    scheme: upto
                    network: eip155:8453
                    extra:
                      facilitatorAddress: '0x8f5cb67b49555e614892b7233cfddebfb746e531'
                  - x402Version: 2
                    scheme: upto
                    network: eip155:84532
                    extra:
                      facilitatorAddress: '0x8f5cb67b49555e614892b7233cfddebfb746e531'
                  - x402Version: 2
                    scheme: upto
                    network: eip155:137
                    extra:
                      facilitatorAddress: '0x8f5cb67b49555e614892b7233cfddebfb746e531'
                  - x402Version: 2
                    scheme: upto
                    network: eip155:42161
                    extra:
                      facilitatorAddress: '0x8f5cb67b49555e614892b7233cfddebfb746e531'
                  - x402Version: 2
                    scheme: upto
                    network: eip155:480
                    extra:
                      facilitatorAddress: '0x8f5cb67b49555e614892b7233cfddebfb746e531'
                  - x402Version: 2
                    scheme: batch-settlement
                    network: eip155:8453
                    extra:
                      receiverAuthorizer: '0x4A8f3C2e1D9b7F6a0E5c8B3d2A1f9E7c6D4b2A0f'
                  - x402Version: 2
                    scheme: batch-settlement
                    network: eip155:84532
                    extra:
                      receiverAuthorizer: '0x4A8f3C2e1D9b7F6a0E5c8B3d2A1f9E7c6D4b2A0f'
                  - x402Version: 2
                    scheme: batch-settlement
                    network: eip155:137
                    extra:
                      receiverAuthorizer: '0x4A8f3C2e1D9b7F6a0E5c8B3d2A1f9E7c6D4b2A0f'
                  - x402Version: 2
                    scheme: batch-settlement
                    network: eip155:42161
                    extra:
                      receiverAuthorizer: '0x4A8f3C2e1D9b7F6a0E5c8B3d2A1f9E7c6D4b2A0f'
                  - x402Version: 2
                    scheme: batch-settlement
                    network: eip155:480
                    extra:
                      receiverAuthorizer: '0x4A8f3C2e1D9b7F6a0E5c8B3d2A1f9E7c6D4b2A0f'
                  - x402Version: 1
                    scheme: exact
                    network: base
                  - x402Version: 1
                    scheme: exact
                    network: base-sepolia
                  - x402Version: 1
                    scheme: exact
                    network: solana
                    extra:
                      feePayer: BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP
                  - x402Version: 1
                    scheme: exact
                    network: solana-devnet
                    extra:
                      feePayer: BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP
              extensions:
                type: array
                description: The list of supported x402 extensions.
                items:
                  type: string
                example:
                  - bazaar
                  - eip2612GasSponsoring
              signers:
                type: object
                description: A map of CAIP-2 network or protocol family patterns to their supported signer addresses.
                additionalProperties:
                  type: array
                  items:
                    type: string
                example:
                  eip155:*:
                    - '0x8f5cb67b49555e614892b7233cfddebfb746e531'
                    - '0x67b9ce703d9ce658d7c4ac3c289cea112fe662af'
                    - '0x68a96f41ff1e9f2e7b591a931a4ad224e7c07863'
                    - '0x97acce27d5069544480bde0f04d9f47d7422a016'
                    - '0xa32ccda98ba7529705a059bd2d213da8de10d101'
                  solana:*:
                    - BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP
                    - BFK9TLC3edb13K6v4YyH3DwPb5DSUpkWvb7XnqCL9b4F
                    - D6ZhtNQ5nT9ZnTHUbqXZsTx5MH2rPFiBBggX4hY1WePM
                    - GVJJ7rdGiXr5xaYbRwRbjfaJL7fmwRygFi1H6aGqDveb
                    - Hc3sdEAsCGQcpgfivywog9uwtk8gUBUZgsxdME1EJy88
            required:
              - kinds
              - extensions
              - signers
    ForbiddenError:
      description: User forbidden from performing the action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                errorType: forbidden
                errorMessage: User forbidden from performing the action.
  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-5af8-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-5af8-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-5af8-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
      - name: Non-custodial
        x-groups:
          - name: User Wallets
            tags:
              - End User Account Management
              - End User Accounts
          - name: API Key Wallets
            tags:
              - EVM Accounts
              - EVM Smart Accounts
              - Solana Accounts
        tags:
          - Policy Engine
          - Wallet Webhooks
    tags:
      - Accounts
      - End User Account Management
      - End User Accounts
      - EVM Accounts
      - EVM Smart Accounts
      - Solana Accounts
      - Policy Engine
      - Wallet Webhooks
  - name: Payments
    x-groups:
      - name: Acceptance
        tags:
          - Payment Sessions
          - Disbursements
      - tags:
          - Deposit Destinations
          - Payment Methods
          - Transfers
          - Onramp
          - x402 Facilitator
    tags:
      - Payment Sessions
      - Disbursements
      - Deposit Destinations
      - Payment Methods
      - Transfers
      - Onramp
      - x402 Facilitator
  - name: Trading
    tags:
      - EVM Swaps
  - name: Onchain Tools
    tags:
      - EVM Token Balances
      - Faucets
      - Onchain Data
      - Solana Token Balances
      - SQL API
  - name: Customers
    tags:
      - Customers
  - name: Webhooks
    tags:
      - Webhooks