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: Embedded Wallets x-audience: public x-slo-tier: tier: ga description: |- The Embedded Wallet APIs enable end users to directly create, manage, and use their accounts. They are typically accessed via the CDP Web SDK. End users authenticate with the APIs via the `InitiateAuthentication` endpoint, and use the returned access token and refresh token to authenticate with the other endpoints. The Embedded Wallet APIs offer end users full control over their accounts, including the ability to sign transactions and messages, and to export their accounts' private keys. There are three authentication credentials involved in the Embedded Wallet APIs: 1. **Access Token**: A JWT signed by CDP, encoded in base64. This is used to identify the end user, and is issued after the end user has signed in using one of the provided authentication methods. The APIs provide multiple mechanisms for end user authentication, including custom auth JWT authentication, email one-time-password (OTP) authentication, and social sign-in. 2. **Refresh Token**: A cryptographically random string, set as the `cdp_refresh_token` cookie in the end user's browser. By hitting the `RefreshAccessToken` endpoint, the included refresh token can be used to obtain a new access token without requiring the end user to sign in again. 3. **Temporary Wallet Secret (TWS)**: Requests to signing-related endpoints must also be authenticated using a **Temporary Wallet Secret** (TWS) generated on the end user's browser/device. Typically, this is done using the CDP Embedded Wallet SDK. The Temporary Wallet Secret follows similar semantics to the Wallet Secret used by the EVM and Solana Account APIs, with the following key differences: - The end user must register their TWS with the End User Accounts APIs before it can be used. - Temporary Wallet Secrets have a time-to-live (TTL) defined by the `validUntil` field in the TWS registration request. - A maximum of five TWS's can be registered for a single end user at any given time. ## 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: End User Accounts x-audience: public x-slo-tier: tier: ga description: |- The End User Accounts 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 Accounts APIs are accessed by the developer's servers and authenticated by the developer's CDP API key. - 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). **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. - 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 #### Apple Pay Onramp This use case allows you to offer an Apple 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 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-&-offramp/onramp-apis/apple-pay-onramp-api) 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: 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 Embedded Wallets End user criteria apply to operations performed by end users via embedded 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). **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. - 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: 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: ga 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/end-users: post: summary: Create an 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 Accounts 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 Accounts 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 Accounts 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 an 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 Accounts 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. 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 Accounts security: - apiKeyAuth: [] parameters: - name: email in: query required: false description: The email address to search for across all email-based authentication methods. schema: type: string format: 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: type: string pattern: ^\+[1-9]\d{1,14}$ example: '+14155552671' 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' 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, 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, 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 an EVM account to an 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 Accounts x-audience: public security: - apiKeyAuth: [] parameters: - 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 - $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 an EVM smart account to an 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 Accounts 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 a Solana account to an 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 Accounts x-audience: public security: - apiKeyAuth: [] parameters: - 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 - $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 a private key for an end user 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 Accounts 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 a transaction with 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: - Embedded Wallets 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': 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/embedded-wallet-api/end-users/{userId}/evm/send/transaction: post: x-audience: public summary: Send a transaction with 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: - Embedded Wallets 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': 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/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: - Embedded Wallets 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 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/get-started/supported-networks#supported-networks 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 '401': $ref: '#/components/responses/UnauthorizedError' '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. 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 an EIP-191 message with 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)> ` before being signed. operationId: signEvmMessageWithEndUserAccount tags: - Embedded Wallets 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' '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 with 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: - Embedded Wallets 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' '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: - Embedded Wallets 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: - Embedded Wallets 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 an end user account 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: - Embedded Wallets 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 an end user account 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: - Embedded Wallets 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 an end user account 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: - Embedded Wallets 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: - Embedded Wallets 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. default: false 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' '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 a 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: - Embedded Wallets 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/ 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. 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/embedded-wallet-api/end-users/{userId}/solana/sign/message: post: x-audience: public summary: Sign a 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: - Embedded Wallets 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' '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 a transaction with 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: - Embedded Wallets 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': 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 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/send/transaction: post: x-audience: public summary: Send a transaction with 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: - Embedded Wallets 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': 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/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: - Embedded Wallets 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/get-started/supported-networks#supported-networks 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' '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 an 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 an 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 an 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 an 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 a 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 a 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 a 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 an 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)> ` 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. default: false 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 for an operationID 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 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 a 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 a 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 an 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 an 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 an 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 a 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 an 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 a 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/ 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. '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 a user operation for EVM Smart Account 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/ 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. 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 a 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 a 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 a 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. '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 a 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. '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 a price estimate for a swap 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 a 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: x-audience: public summary: List EVM token balances 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. **Note:** This endpoint is still under development and does not yet provide strong freshness guarantees. Specifically, balances of new tokens can, on occasion, take up to ~30 seconds to appear, while balances of tokens already belonging to an address will generally be close to chain tip. Freshness of new token balances will improve over the coming weeks. 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 a 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 a 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 a 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 a 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 or get account by name 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 a 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 a 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 a 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 a 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 a 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 an 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 a 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 a 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 a 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 a 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 Tables - `.events` - Base mainnet decoded event logs with parameters, event signature, topics, and more. - `.transactions` - Base mainnet transaction data including hash, block number, gas usage. - `.blocks` - Base mainnet block information. - `.encoded_logs` - Encoded log data of event logs that aren't able to be decoded by our event decoder (ex: log0 opcode). - `.decoded_user_operations` - Decoded user operations data including hash, block number, gas usage, builder codes, entrypoint version, and more. - `.transaction_attributions` - Information about the attributions of a transaction to a builder and associated builder codes. ### Supported Networks - Base Mainnet: `base` - Base Sepolia: `base_sepolia` So for example, valid tables are: `base.events`, `base_sepolia.events`, `base.transactions`, etc. ### 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 schemas 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 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. **Note:** This endpoint provides <1 second freshness from chain tip, <500ms response latency for wallets with reasonable token history, and 99.9% uptime for production use. 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 using flexible filtering. ### Event Types **Onchain Events** - Monitor Base mainnet with microsecond precision: - `onchain.activity.detected` - Smart contract events, transfers, swaps, NFT activity - **Requires** `labels` for filtering (e.g., `contract_address`, `event_name`) **Onramp/Offramp Events** - Transaction lifecycle notifications: - `onramp.transaction.created`, `onramp.transaction.updated` - `onramp.transaction.success`, `onramp.transaction.failed` - `offramp.transaction.created`, `offramp.transaction.updated` - `offramp.transaction.success`, `offramp.transaction.failed` - **No labels required** - maximum simplicity for transaction monitoring **Payments Transfers Events** - Transfer lifecycle notifications: - `payments.transfers.quoted` - Transfer created and awaiting execution - `payments.transfers.processing` - Transfer execution in progress - `payments.transfers.completed` - Transfer completed successfully - `payments.transfers.failed` - Transfer failed - `payments.transfers.travel_rule_incomplete` - Travel rule information is missing - `payments.transfers.travel_rule_completed` - Travel rule information has been provided and the transfer will proceed - **No labels required** - enable the transfers webhook to monitor status transitions **Wallet Events** - Wallet activity notifications: - `wallet.activity.detected` ### Webhook Signature Verification All webhooks include cryptographic signatures for security. The signature secret is returned in `secret` field when creating a subscription. **Note:** Webhooks are in beta and this interface is subject to change. See the [verification guide](https://docs.cdp.coinbase.com/onramp-&-offramp/webhooks#webhook-signature-verification) for implementation details. ### Onchain Label Filtering For `onchain.activity.detected` events, use `labels` for precise filtering with AND logic (max 20 labels per webhook). **Allowed labels** (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`) **Examples**: - **Liquidity Pool Monitor**: `{"network": "base-mainnet", "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d", "event_name": "Burn"}` - **Price Oracle Tracker**: `{"network": "base-mainnet", "contract_address": "0xbac4a9428ea707c51f171ed9890c3c2fa810305d", "event_name": "PriceUpdated"}` - **DeFi Protocol Activity**: `{"network": "base-mainnet", "contract_address": "0x45c6e6a47a711b14d8357d5243f46704904578e3", "event_name": "Deposit"}` 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 onramp_transactions: summary: 'Onramp: Transaction lifecycle' value: description: Onramp transaction status webhook. eventTypes: - onramp.transaction.created - onramp.transaction.updated - onramp.transaction.success - onramp.transaction.failed labels: {} target: url: https://api.example.com/webhooks isEnabled: true offramp_transactions: summary: 'Offramp: Transaction lifecycle' value: description: Offramp transaction status webhook. eventTypes: - offramp.transaction.created - offramp.transaction.updated - offramp.transaction.success - offramp.transaction.failed labels: {} 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 details 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 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 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 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 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 a 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 a 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/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 currently only supports the payment method `GUEST_CHECKOUT_APPLE_PAY`. For detailed integration instructions and to get access to this API, refer to the [Apple Pay Onramp API docs](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/apple-pay-onramp-api). 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-&-offramp/onramp-apis/apple-pay-onramp-api) 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' 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 button will be rendered on. Required when using the `GUEST_CHECKOUT_APPLE_PAY` payment method and embedding the payment link in an iframe. type: string example: pay.coinbase.com required: - paymentCurrency - purchaseCurrency - paymentMethod - destinationAddress - destinationNetwork - phoneNumber - email - agreementAcceptedAt - phoneNumberVerifiedAt - 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' 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. 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). 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 '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/RateLimitExceeded' '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 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: type: object 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. 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 when they successfully complete a transaction. This URI will be embedded in the returned onramp URI 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 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 required: - destinationAddress - purchaseCurrency - destinationNetwork 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' required: - limits examples: default: value: limits: - limitType: weekly_spending currency: USD limit: '500' remaining: '400' - limitType: lifetime_transactions limit: '15' remaining: '12' '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 by submitting identity information. Only phone number is currently supported as a userId. 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: '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' webhooks: {} components: securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: JWT description: A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the [Generate Bearer Token](https://docs.cdp.coinbase.com/api-reference/v2/authentication#2-generate-bearer-token) section of our Authentication docs for information on how to generate your Bearer Token. endUserAuth: x-audience: public type: http scheme: bearer bearerFormat: JWT description: A JWT signed using the developer's own JWT private key (in the case of JWT authentication), or an end user JWT signed by CDP, encoded in base64. This is used for End User Account APIs. schemas: 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: type: string description: The email address of the end user. example: user@example.com format: email 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: type: string description: The phone number of the end user in E.164 format. example: '+12055555555' pattern: ^\+[1-9]\d{1,14}$ 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 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' 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' 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' 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 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 - 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 - policy_violation - policy_in_use - account_limit_exceeded - network_not_tradable - guest_permission_denied - guest_region_forbidden - guest_transaction_limit - guest_transaction_count - phone_number_verification_expired - document_verification_failed - recipient_allowlist_violation - recipient_allowlist_pending - refund_expired - travel_rules_recipient_violation - source_account_invalid - target_account_invalid - source_account_not_found - target_account_not_found - source_asset_not_supported - target_asset_not_supported - target_email_invalid - target_onchain_address_invalid - transfer_amount_invalid - transfer_asset_not_supported - 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 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 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). forbidden: |- This error occurs when you don't have permission to access the resource. **Steps to resolve:** 1. Verify your permissions to access the resource 2. Ensure that you are the owner of the requested resource idempotency_error: |- This error occurs when an idempotency key is reused with different parameters. **Steps to resolve:** 1. Generate a new UUID v4 for each unique request 2. Only reuse idempotency keys for exact request duplicates 3. Track used keys within your application **Example idempotency key implementation:** ```typescript lines wrap import { v4 as uuidv4 } from 'uuid'; function createIdempotencyKey() { return uuidv4(); } ``` internal_server_error: |- This indicates an unexpected error that occurred on the CDP servers. **Important**: If you encounter this error, please note that your operation's status should be treated as unknown by your application, as it could have been a success within the CDP back-end. **Steps to resolve:** 1. Retry your request after a short delay 2. If persistent, contact CDP support with: - Your correlation ID - Timestamp of the error - Request details 3. Consider implementing retry logic with an exponential backoff **Note:** These errors are automatically logged and monitored by CDP. invalid_request: |- This error occurs when the request is malformed or contains invalid data, including issues with the request body, query parameters, path parameters, or headers. **Steps to resolve:** 1. Check all required fields and parameters are present 2. Ensure request body (if applicable) follows the correct schema 3. Verify all parameter formats match the API specification: - Query parameters - Path parameters - Request headers 4. Validate any addresses, IDs, or other formatted strings meet requirements **Common validation issues:** - Missing required parameters - Invalid parameter types or formats - Malformed JSON in request body - Invalid enum values #### Transfer-specific validation errors The following transfer validation scenarios return `errorType: "invalid_request"`. Use the `errorMessage` field to identify the specific case. | Scenario | Example `errorMessage` | |----------|----------------------| | Source account ID is malformed | `"source is invalid."` | | Target account ID is malformed | `"target is invalid."` | | Source account does not exist | `"source not found."` | | Target account does not exist | `"target not found."` | | Asset not supported at source | `"source is not supported."` | | Asset not supported at target | `"target is not supported."` | | Target email address is malformed | `"target has an invalid email format."` | | Target onchain address is invalid for network | `"The recipient address is invalid for the selected network."` | | Asset not supported for this transfer route | `"Transfer asset pair is not supported."` | | Insufficient balance | `"Insufficient funds to complete this transfer."` | | Asset mismatch between request fields | `"Currency mismatch in request."` | | Metadata has too many keys | `"Metadata has too many keys. Up to 10 key/value pairs are permitted."` | | Metadata key exceeds length limit | `"Metadata key is too long. Each key must be less than or equal to 40 characters."` | | Metadata value exceeds length limit | `"Metadata value is too long. Each value must be less than or equal to 500 characters."` | | Travel rule fields missing | `"Travel rule information is incomplete. Missing fields: ..."` | | Recipient address not in account allowlist | `"Your coinbase account allowlist does not include this address. Please update your allowlist at https://www.coinbase.com/settings/allowlist"` | invalid_sql_query: |- This error occurs when the SQL query is invalid or not allowed. **Common causes:** - Using non-SELECT SQL statements (INSERT, UPDATE, DELETE, etc.) - Invalid table or column names - Syntax errors in SQL query - Query exceeds character limit - Too many JOIN operations invalid_signature: |- This error occurs when the signature provided for the given user operation is invalid. **Steps to resolve:** 1. Verify the signature was generated by the correct owner account 2. Ensure the signature corresponds to the exact user operation hash 3. Check that the signature format matches the expected format 4. Confirm you're using the correct network for the Smart Account **Common causes:** - Using wrong owner account to sign - Signing modified/incorrect user operation data - Malformed signature encoding - Network mismatch between signature and broadcast malformed_transaction: |- This error occurs when the transaction data provided is not properly formatted or is invalid. **Steps to resolve:** 1. Verify transaction encoding: - **EVM networks**: Check RLP encoding is correct - **Solana**: Validate base64 encoding 2. Ensure all required transaction fields are present 3. Validate transaction parameters are within acceptable ranges 4. Check that the transaction type is supported on the target network (see our [Supported Networks](https://docs.cdp.coinbase.com/get-started/supported-networks) page for more details) **Common causes:** - Invalid hex encoding for EVM transactions - Missing required transaction fields - Incorrect parameter formats - Unsupported transaction types - Network-specific transaction format mismatches not_found: |- This error occurs when the resource specified in your request doesn't exist or you don't have access to it. **Steps to resolve:** 1. Verify the resource ID/address/account exists 2. Check your permissions to access the resource 3. Ensure you're using the correct network/environment 4. Confirm the resource hasn't been deleted **Common causes:** - Mistyped addresses - Accessing resources from the wrong CDP project - Resource was deleted or hasn't been created yet payment_method_required: |- This error occurs when a payment method is required to complete the requested operation but none is configured or available. **Steps to resolve:** 1. Add a valid payment method to your account using the [CDP Portal](https://portal.cdp.coinbase.com) 2. Ensure your payment method is valid and not expired **Common causes:** - No payment method configured on the account - Payment method is expired payment_required: |- This error occurs when an x402 payment is required to access the requested resource. **Steps to resolve:** 1. Include a valid x402 payment header in your request 2. Ensure the payment meets the resource's pricing requirements settlement_failed: |- This error occurs when an x402 payment was verified but settlement on-chain failed. **Steps to resolve:** 1. Retry the request with a new payment 2. Ensure the payment asset has sufficient balance for settlement rate_limit_exceeded: |- This error occurs when you've exceeded the API rate limits. **Steps to resolve:** 1. Implement exponential backoff 2. Cache responses where possible 3. Wait for rate limit window to reset **Best practices:** ```typescript lines wrap async function withRetry(fn: () => Promise) { let delay = 1000; while (true) { try { return await fn(); } catch (e) { if (e.errorType === "rate_limit_exceeded") { await sleep(delay); delay *= 2; continue; } throw e; } } } ``` request_canceled: |- This error occurs when the client cancels an in-progress request before it completes. **Steps to resolve:** 1. Check client-side timeout configurations 2. Review request cancellation logic in your code 3. Consider increasing timeout thresholds for long-running operations 4. Implement request tracking to identify premature cancellations **Best practices:** ```typescript lines wrap async function withTimeout(promise: Promise, timeoutMs: number): Promise { const timeout = new Promise((_, reject) => { setTimeout(() => { reject(new Error("Operation timed out")); }, timeoutMs); }); try { return await Promise.race([promise, timeout]); } catch (error) { // Handle timeout or cancellation throw error; } } ``` service_unavailable: |- This error occurs when the CDP API is temporarily unable to handle requests due to maintenance or high load. **Steps to resolve:** 1. Retry your request after a short delay 2. If persistent, contact CDP support with: - The timestamp of the error - Request details 3. Consider implementing retry logic with an exponential backoff **Note:** These errors are automatically logged and monitored by CDP. timed_out: |- This error occurs when a request exceeds the maximum allowed processing time. **Steps to resolve:** 1. Break down large requests into smaller chunks (if applicable) 2. Implement retry logic with exponential backoff 3. Use streaming endpoints for large data sets **Example retry implementation:** ```typescript lines wrap async function withRetryAndTimeout( operation: () => Promise, maxRetries = 3, timeout = 30000, ): Promise { let attempts = 0; while (attempts < maxRetries) { try { return await Promise.race([ operation(), new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), timeout) ), ]); } catch (error) { attempts++; if (attempts === maxRetries) throw error; // Exponential backoff await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempts) * 1000) ); } } throw new Error("Max retries exceeded"); } ``` unauthorized: |- This error occurs when authentication fails. **Steps to resolve:** 1. Verify your CDP API credentials: - Check that your API key is valid - Check that your Wallet Secret is properly configured 2. Validate JWT token: - Not expired - Properly signed - Contains required claims 3. Check request headers: - Authorization header present - X-Wallet-Auth header included when required **Security note:** Never share your Wallet Secret or API keys. policy_in_use: |- This error occurs when trying to delete a Policy that is currently in use by at least one project or account. **Steps to resolve:** 1. Update project or accounts to remove references to the Policy in question. 2. Retry your delete request. network_not_tradable: |- This error occurs when the selected asset cannot be purchased on the selected network in the user's location. **Steps to resolve:** 1. Verify the asset is tradable on the selected network 2. Check the user's location to ensure it is allowed to purchase the asset on the selected network **Common causes:** - Users in NY are not allowed to purchase USDC on any network other than Ethereum guest_permission_denied: |- This error occurs when the user is not allowed to complete onramp transactions as a guest. **Steps to resolve:** 1. Redirect the user to create a Coinbase account to buy and send crypto. guest_region_forbidden: |- This error occurs when guest onramp transactions are not allowed in the user's region. **Steps to resolve:** 1. Redirect the user to create a Coinbase account to buy and send crypto. guest_transaction_limit: |- This error occurs when the user has reached the weekly guest onramp transaction limit. **Steps to resolve:** 1. Inform the user they have reached their weekly limit and will have to wait until next week. guest_transaction_count: |- This error occurs when the user has reached the lifetime guest onramp transaction count limit. **Steps to resolve:** 1. Redirect the user to create a Coinbase account to buy and send crypto. phone_number_verification_expired: |- This error occurs when the user's phone number verification has expired. Use of guest Onramp requires the user's phone number to be verified every 60 days. **Steps to resolve:** 1. Re-verify the user's phone number via OTP. 2. Retry the request with the phoneNumberVerifiedAt field set to new verification timestamp. document_verification_failed: |- This error occurs when the user has not verified their identity for their coinbase.com account. **Steps to resolve:** 1. Verify your coinbase account identity with valid documents at https://www.coinbase.com/settings/account-levels. recipient_allowlist_violation: |- This error occurs when the user is not allowed to receive funds at this address, according to their coinbase account allowlist. **Steps to resolve:** 1. Either disable the allowlist or add the wallet address at https://www.coinbase.com/settings/allowlist 2. Wait approximately 2 days for updates to take effect. recipient_allowlist_pending: |- This error occurs when the user is not allowed to receive funds at this address, because changes to their coinbase account allowlist are pending. **Steps to resolve:** 1. Wait approximately 2 days for updates to take effect. refund_expired: Returned when a refund attempt is made after the payment session's refund deadline has passed. The payment session can no longer be refunded. travel_rules_recipient_violation: |- This error occurs when the user is not allowed to receive funds at this address, because it violates travel rules. **Steps to resolve:** 1. Ensure your desired transfer is not blocked by local travel regulations. mfa_already_enrolled: |- This error occurs when attempting to enroll in an MFA method that the user has already enrolled in. **Steps to resolve:** 1. Check if the user is already enrolled in the MFA method before initiating enrollment 2. To update or reset MFA, remove the existing enrollment first (if supported) 3. Use a different MFA method if multiple options are available mfa_invalid_code: |- This error occurs when the MFA code provided is incorrect or has already been used. **Steps to resolve:** 1. Verify the user entered the correct code from their authenticator app 2. Ensure the code is current (TOTP codes expire after 30 seconds) 3. Check that the device time is synchronized correctly 4. Ask the user to generate a new code and try again **Common causes:** - Typing errors in the 6-digit code - Using an expired TOTP code - Device clock drift on user's authenticator app - Attempting to reuse a previously submitted code mfa_flow_expired: |- This error occurs when the MFA enrollment or verification session has expired. **Steps to resolve:** 1. Restart the MFA enrollment or verification flow 2. Complete the flow within the allowed time window (typically 5 minutes) 3. Ensure the user doesn't leave the flow idle for extended periods **Note:** MFA sessions expire automatically for security purposes. mfa_required: |- This error occurs when attempting to perform a sensitive operation that requires MFA verification, but the user has not completed MFA verification. **Steps to resolve:** 1. Initiate the MFA verification flow using the `/mfa/verify/{mfaMethod}/init` endpoint 2. Prompt the user to enter their MFA code 3. Submit the verification using the `/mfa/verify/{mfaMethod}/submit` endpoint 4. Use the returned access token with MFA claim for the sensitive operation 5. Retry the original request with the new MFA-verified token **Operations requiring MFA:** - Transactions Sign/Send - Key export - Account management actions (when configured) mfa_not_enrolled: |- This error occurs when attempting to verify MFA for a user who has not enrolled in any MFA method. **Steps to resolve:** 1. Check if the user has enrolled in MFA before attempting verification 2. Guide the user through MFA enrollment first using the `/mfa/enroll/{mfaMethod}/init` endpoint 3. Complete enrollment before requiring MFA verification source_account_invalid: |- This error occurs when the source account specified in the transfer request is invalid or malformed. **Steps to resolve:** 1. Verify the account ID format is correct (e.g., `account_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) 2. Ensure the account ID belongs to your CDP entity 3. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` **Common causes:** - Malformed account ID - Typo in the account ID target_account_invalid: |- This error occurs when the target account specified in the transfer request is invalid or malformed. **Steps to resolve:** 1. Verify the account ID format is correct (e.g., `account_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) 2. Ensure the account exists and can receive funds 3. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` **Common causes:** - Malformed account ID - Typo in the account ID source_account_not_found: |- This error occurs when the source account specified in the transfer does not exist. **Steps to resolve:** 1. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` target_account_not_found: |- This error occurs when the target account specified in the transfer does not exist. **Steps to resolve:** 1. Verify the account ID exists by calling `GET /v2/accounts/{accountId}` or `GET /v2/accounts` source_asset_not_supported: |- This error occurs when the asset specified in the transfer source is not supported for this transfer type. **Steps to resolve:** 1. Check the list of supported assets for the source account type 2. Verify the asset symbol is correctly specified (e.g., `usdc`, `usdt`) **Common causes:** - Unsupported asset for the transfer route - Incorrect asset symbol target_asset_not_supported: |- This error occurs when the asset specified in the transfer target is not supported for this transfer type. **Steps to resolve:** 1. Check the list of supported assets for the target 2. Verify the asset symbol is correctly specified (e.g., `usdc`, `usdt`) 3. Ensure the target can receive this asset type **Common causes:** - Asset not supported by the target - Unsupported conversion between source and target assets target_email_invalid: |- This error occurs when the email address specified as the transfer target is invalid. **Steps to resolve:** 1. Verify the email address format is valid (e.g., `user@example.com`) 2. Check for typos in the email address 3. Ensure the email domain is valid **Common causes:** - Invalid email format - Missing @ symbol or domain - Typo in the email address target_onchain_address_invalid: |- This error occurs when the onchain address specified as the transfer target is invalid for the specified network. **Steps to resolve:** 1. Ensure the network is supported for the transfer type 2. Verify the address format matches the target network 3. Ensure you haven't mixed up addresses from different networks **Common causes:** - Network not supported for the transfer type - Address format doesn't match network - Address from a different blockchain network transfer_amount_invalid: |- This error occurs when the transfer amount is invalid. **Steps to resolve:** 1. Ensure the amount is a positive number and greater than $1 USD equivalent amount 2. Verify the amount format is a valid decimal string (e.g., `"100.50"`) 3. Check the number of decimal places for the asset **Common causes:** - Zero or negative amount - Too many decimal places for the asset - Amount below minimum threshold ($1 USD equivalent amount) transfer_asset_not_supported: |- This error occurs when the asset specified for the transfer is not supported. **Steps to resolve:** 1. Check the list of supported assets for transfers 2. Verify the asset symbol is correctly specified 3. Ensure the asset is supported for the transfer route (source → target) **Common causes:** - Asset not supported for transfers - Incorrect asset symbol 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 Url: type: string format: uri minLength: 11 maxLength: 2048 pattern: ^https?://.*$ description: A valid HTTP or HTTPS URL. example: https://example.com 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 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 Asset: type: string minLength: 1 maxLength: 42 description: The symbol of the asset (e.g., eth, usd, usdc, usdt). example: usd 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' 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' required: - network - userOpHash - calls - status 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 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: type: object nullable: true description: The estimated gas fee for the swap. allOf: - $ref: '#/components/schemas/TokenFee' protocolFee: type: object nullable: true description: The estimated protocol fee for the swap. allOf: - $ref: '#/components/schemas/TokenFee' 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: type: object nullable: true description: Details of the allowances that the taker must set in order to execute the swap successfully. Null if no allowance is required. 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' balance: type: object nullable: true description: Details of the balance of the `fromToken` that the `taker` must hold. Null if the `taker` has a sufficient balance. 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' 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: type: string nullable: true 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' 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' CreateSwapQuoteResponse: title: CreateSwapQuoteResponse allOf: - type: object properties: permit2: type: object nullable: true 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. 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 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/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 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/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 Description: type: string minLength: 0 maxLength: 500 description: A human-readable description. example: A description of the resource. 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 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 WebhookTarget: type: object description: | Target configuration for webhook delivery. Specifies the destination URL and any custom headers to include in webhook requests. required: - url properties: url: allOf: - $ref: '#/components/schemas/Url' description: The webhook URL to deliver events to. example: https://api.example.com/webhooks headers: type: object description: Additional headers to include in webhook requests. additionalProperties: type: string example: Authorization: Bearer token123 Content-Type: application/json example: url: https://api.example.com/webhooks headers: Authorization: Bearer token123 Content-Type: application/json WebhookSubscriptionResponse: type: object description: Response containing webhook subscription details. required: - subscriptionId - eventTypes - isEnabled - secret - target - createdAt properties: createdAt: type: string format: date-time description: When the subscription was created. example: '2025-01-15T10:30:00Z' updatedAt: type: string format: date-time description: When the subscription was last updated. example: '2025-01-16T14:00:00Z' description: allOf: - $ref: '#/components/schemas/Description' description: Description of the webhook subscription. example: Subscription for token transfer events eventTypes: type: array description: | Types of events to subscribe to. Event types follow a dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created", "acceptance.payment_session.authorization_succeeded"). items: type: string example: - onchain.activity.detected isEnabled: type: boolean description: Whether the subscription is enabled. example: true metadata: allOf: - $ref: '#/components/schemas/Metadata' - type: object properties: secret: type: string format: uuid deprecated: true description: Use the root-level `secret` field instead. Maintained for backward compatibility only. example: 123e4567-e89b-12d3-a456-426614174000 description: Additional metadata for the subscription. example: secret: 123e4567-e89b-12d3-a456-426614174000 secret: type: string format: uuid description: Secret for webhook signature validation. example: 123e4567-e89b-12d3-a456-426614174000 subscriptionId: type: string format: uuid description: Unique identifier for the subscription. example: 123e4567-e89b-12d3-a456-426614174000 target: $ref: '#/components/schemas/WebhookTarget' labels: type: object description: | Multi-label filters using total overlap logic. Total overlap means the subscription only triggers when events contain ALL these key-value pairs. Present when subscription uses multi-label format. additionalProperties: type: string example: env: dev team: payments contract_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' example: subscriptionId: 123e4567-e89b-12d3-a456-426614174000 eventTypes: - onchain.activity.detected isEnabled: true labels: contract_address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' event_name: Transfer network: base-mainnet transaction_to: '0xf5042e6ffac5a625d4e7848e0b01373d8eb9e222' description: USDC Transfer events to specific address. createdAt: '2025-11-12T09:19:52.051Z' updatedAt: '2025-11-13T11:30:00.000Z' metadata: secret: a1b2c3d4-e5f6-7890-abcd-ef1234567890 secret: a1b2c3d4-e5f6-7890-abcd-ef1234567890 target: url: https://api.example.com/webhooks WebhookSubscriptionListResponse: allOf: - type: object description: Response containing a list of webhook subscriptions. required: - subscriptions properties: subscriptions: type: array description: The list of webhook subscriptions. items: $ref: '#/components/schemas/WebhookSubscriptionResponse' - $ref: '#/components/schemas/ListResponse' WebhookSubscriptionRequest: type: object description: | Request to create a new webhook subscription with support for multi-label filtering. properties: description: allOf: - $ref: '#/components/schemas/Description' description: Description of the webhook subscription. example: Subscription for token transfer events eventTypes: type: array description: | Types of events to subscribe to. Event types follow a dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created", "acceptance.payment_session.authorization_succeeded"). The subscription will only receive events matching these types AND the label filter(s). items: type: string 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. See [allowed labels for onchain webhooks](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/webhooks/create-webhook-subscription#onchain-label-filtering). additionalProperties: type: string example: network: base-mainnet contract_address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' event_name: Transfer required: - eventTypes - isEnabled - target WebhookSubscriptionUpdateRequest: type: object description: | Request to update an existing webhook subscription. properties: description: allOf: - $ref: '#/components/schemas/Description' description: Description of the webhook subscription. example: Updated subscription for token transfer events eventTypes: type: array description: | Types of events to subscribe to. Event types follow a three-part dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created"). items: type: string 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. **Note:** Currently, labels are supported for onchain webhooks only. See [allowed labels for onchain webhooks](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/webhooks/create-webhook-subscription#onchain-label-filtering). Omit to receive all events for the selected event types. additionalProperties: type: string example: network: base-mainnet contract_address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' event_name: Transfer 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 X402Version: type: integer description: The version of the x402 protocol. enum: - 1 - 2 example: 2 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 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 x402V2PaymentRequirements: type: object description: The x402 protocol payment requirements that the resource server expects the client's payment payload to meet. properties: scheme: type: string description: The scheme of the payment protocol to use. Supported schemes are `exact` and `upto`. enum: - exact - upto example: exact network: type: string description: The network of the blockchain to send payment on in caip2 format. example: eip155:1 asset: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' amount: type: string description: The amount to pay for the resource in atomic units of the payment asset. example: '1000000' payTo: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ 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 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 x402V2PaymentPayload: type: object description: The x402 protocol payment payload that the client attaches to x402-paid API requests to the resource server in the X-PAYMENT header. properties: x402Version: $ref: '#/components/schemas/X402Version' 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' 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 description: The x402 protocol payment payload that the client attaches to x402-paid API requests to the resource server in the X-PAYMENT header. properties: x402Version: $ref: '#/components/schemas/X402Version' scheme: type: string description: The scheme of the payment protocol to use. Currently, the only supported scheme is `exact`. enum: - exact example: exact network: type: string description: The network of the blockchain to send payment on. enum: - base-sepolia - base - solana-devnet - solana - polygon 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 X-PAYMENT header. For EVM networks, smart account signatures can be longer than 65 bytes. oneOf: - $ref: '#/components/schemas/x402V2PaymentPayload' - $ref: '#/components/schemas/x402V1PaymentPayload' x402V1PaymentRequirements: type: object description: The x402 protocol payment requirements that the resource server expects the client's payment payload to meet. 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: type: string description: The network of the blockchain to send payment on. enum: - base-sepolia - base - solana-devnet - solana - polygon 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: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' maxTimeoutSeconds: type: integer description: The maximum time in seconds for the resource server to respond. example: 10 asset: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ 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' 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 - 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: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ 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 - 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: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ 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 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 example: exact network: type: string description: The network of the blockchain. example: base enum: - base-sepolia - base - solana-devnet - solana - polygon - eip155:8453 - eip155:84532 - eip155:137 - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp - solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 - avalanche - arbitrum - arbitrum-sepolia - world - world-sepolia extra: type: object description: The optional additional scheme-specific payment info. additionalProperties: true example: feePayer: HpabPRRCFbBKSuJr5PdkVvQc85FyxyTWkFM2obBRSvHT required: - x402Version - scheme - network 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 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_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 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 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 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' 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' fields: $ref: '#/components/schemas/OnrampLimitUpgradeIdentityFields' description: Populate the properties that correspond to the `fields` array from the user's `OnrampLimitUpgradeOption`. required: - userId - userIdType - fields example: userId: '+12055555555' userIdType: phone_number fields: ssnLast4: '5678' dateOfBirth: day: '15' month: '08' year: '1990' responses: 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. 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. 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. 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: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e' 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: type: string 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. pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ 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' 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: 1 scheme: exact network: base - x402Version: 1 scheme: exact network: base-sepolia - x402Version: 1 scheme: exact network: solana - x402Version: 1 scheme: exact network: solana-devnet - x402Version: 1 scheme: exact network: polygon extensions: type: array description: The list of supported x402 extensions. items: type: string example: - bazaar 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:*: - '0x1234567890abcdef1234567890abcdef12345678' - '0xabcdef1234567890abcdef1234567890abcdef12' solana:*: - 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d required: - kinds - extensions - signers 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. parameters: 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 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 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 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== x-tagGroups: - name: Payments tags: - Onramp - x402 Facilitator - name: Trading tags: - EVM Swaps - name: Wallets tags: - End User Accounts - EVM Accounts - EVM Smart Accounts - Embedded Wallets - Faucets - Policy Engine - Solana Accounts - name: Onchain Tools tags: - EVM Token Balances - Onchain Data - Solana Token Balances - SQL API - name: Webhooks tags: - Webhooks