Skip to main content
The CDP SDK ships a set of x402 primitives that make it much easier to pay for and gate x402-protected APIs using CDP-managed wallets and the CDP hosted facilitator, with no private keys to store.
The CDP SDK x402 integration is TypeScript only at this time. For Python and Go, use the vanilla x402 packages directly, as shown throughout the Quickstart for Buyers and Quickstart for Sellers.

What the CDP SDK adds

x402 is an HTTP-native payment protocol: a resource server answers a request with 402 Payment Required and a list of accepted payment options, the client signs a payment and retries with a PAYMENT-SIGNATURE header, and a facilitator verifies and settles the payment on-chain. The CDP SDK layers four conveniences on top of the raw @x402/* packages:
  • CDP-managed wallets — no private keys to store. Signing wallets (EVM/Solana EOA or EVM Smart Contract Wallets) are provisioned and signed by CDP.
  • Hosted facilitatorcreateCdpFacilitatorClient() is a drop-in for the CDP hosted facilitator, authenticated with your CDP API keys via JWT.
  • Spend controls — per-payment and rolling caps, network/asset/payee allowlists, and an approaching-limit callback, all enforced client-side.
  • Direct signingaccount.signX402Payment() signs a payment payload with any CDP account for custom payment flows that don’t go through an x402 client SDK (e.g. non-HTTP transports like gRPC or MCP), with no /x402 subpath import required.
Everything is drop-in compatible with the upstream @x402 ecosystem: CdpX402Client extends x402Client, X402Server extends x402HTTPResourceServer, and createCdpFacilitatorClient() returns a standard HTTPFacilitatorClient. The SDK ships no HTTP framework packages of its own, you thread its primitives into the @x402/* client wrappers and server middleware you already use (@x402/fetch, @x402/axios, @x402/express, @x402/hono, @x402/next).

Installation

Everything x402 lives in a subpath export of the main package:

The @x402/* packages are optional peer dependencies

@x402/core, @x402/evm, @x402/svm, and @x402/extensions are optional peer dependencies of @coinbase/cdp-sdk. They are not installed transitively, so a bare npm install @coinbase/cdp-sdk does not pull them in. This keeps consumers who never touch x402 from installing four extra packages, while keeping a single shared copy of each @x402 package for consumers who do. Install the SDK together with x402 primitives:
If using HTTP, install the integration package that fits your use case::
  • Clients: @x402/fetch (wrapFetchWithPayment) or @x402/axios (wrapAxiosWithPayment).
  • Servers: @x402/express, @x402/hono, or @x402/next.

Environment variables

All credential fields can also be passed explicitly via config; explicit values take precedence over env vars.

The primitives

This is the intended way to use x402 with the CDP SDK: pick the primitive that matches what you’re building, and it handles wallet provisioning, scheme registration, and facilitator wiring for you.
  • CDP Client — pay for an x402-protected API from a CDP-managed wallet.
  • CDP Server — gate your API and settle through the CDP facilitator.
  • CDP Facilitator — already have an x402 server; just want CDP settlement.
  • Direct signing — the exception case: sign a payment yourself, outside of a client SDK, for a custom payment flow.

CDP Client

CdpX402Client is a drop-in extension of x402Client that lazily provisions a CDP-managed wallet (no private keys to store) and registers payment schemes on first use. Pass it to any upstream x402 client wrapper — wrapFetchWithPayment (@x402/fetch) or wrapAxiosWithPayment (@x402/axios).
Full example in the repo here. See the Quickstart for Buyers for the full flow, including funding the wallet and discovering services via the Bazaar.

Spend controls

Spend controls are enforced client-side on any x402Client. With CdpX402Client, pass spendControls in the constructor (the SDK wires them internally); for a plain x402Client, call applySpendControls(client, controls) directly.
Supported controls: When a payment is blocked, the client throws a SpendControlError with a machine-readable code. Switch on err.code rather than matching message text:
  • per_payment_cap
  • cumulative_cap
  • network_not_allowed
  • asset_not_allowed
  • payee_not_allowed
  • amount_unparseable
  • ledger_capacity_exceeded
  • configuration_invalid
  • already_applied
Full example in the repo here.

CDP Server

createX402Server provisions a receiver wallet, wires the CDP hosted facilitator, registers payment schemes and extensions, and returns a fully initialized X402Server (which extends x402HTTPResourceServer). Pass it to any framework middleware.
Full example in the repo here (run with APPROACH=2). See the Quickstart for Sellers for Hono/Next.js variants, payToConfig, mainnet setup, and discovery metadata.

CDP Facilitator

If you already run an x402ResourceServer (or call a framework’s paymentMiddleware manually) and just want CDP settlement, drop createCdpFacilitatorClient() in as the facilitator — it returns a standard HTTPFacilitatorClient, so it’s a one-line swap with no other changes to your server setup.
Only API key credentials are needed — no wallet secret, since the facilitator verifies and settles payments but never signs them. Full example in the repo here (run with APPROACH=1).

Direct signing

Every CDP account (EVM server account, EVM smart account, and Solana account) also exposes signX402Payment(paymentRequired, acceptedIndex), which signs an x402 payment payload directly — no CdpX402Client, no wrapFetch/wrapAxios wrapper, no /x402 subpath import. Reach for this only when you’re building a custom payment flow that doesn’t go through a client SDK — e.g. attaching a payment to a non-HTTP transport (gRPC, MCP, a message queue) instead of an HTTP retry.
The same method exists on EVM smart accounts (exact only) and Solana accounts (exact only). See the MCP Server guide for a full example that returns the signed payment in an MCP tool result’s _meta.

Payment schemes

The CDP SDK works with three schemes: A CdpX402Client with an EOA wallet registers exact + upto for EVM and exact for Solana. Smart Contract Wallets register exact only (their ERC-1271/ERC-6492 contract signatures settle via the EIP-3009 exact flow). On the server, createX402Server registers exact + upto for EVM and exact for Solana by default, and rejects upto/batch-settlement on non-EVM networks.

Extensions (auto-injected by createX402Server)

CDP extensions are advertised automatically on every route: Gas-sponsoring declarations are harmless on EIP-3009 / Solana routes. Any extensions you set on a route always take precedence over the auto-injected values — override extensions.bazaar to supply richer discovery metadata.

Networks and RPC

CAIP-2 identifiers are used throughout. createX402Server defaults to Base mainnet + Solana mainnet in "production" and Base Sepolia + Solana Devnet in "development". The SDK exports constant sets (CDP_SERVER_DEFAULT_NETWORKS, CDP_SERVER_DEVELOPMENT_NETWORKS, and their EVM/SVM-only variants) if you want to reference them directly. On the client side, Base and Base Sepolia resolve an RPC automatically via your CDP project’s authenticated node endpoint — no configuration needed. All other EVM networks (Polygon, Arbitrum, Optimism, and so on) have no default RPC; supply one via the rpcUrls config option or the CDP_X402_RPC_URLS env var:

Funding

Client wallets need funds before they can pay. Print a client’s address with client.getAddresses(), then fund it. On Base Sepolia (testnet), fund with USDC using:
  • CDP Faucet (portal): portal.cdp.coinbase.com → “Onchain Tools” → “Faucet”
  • Programmatically: cdp.evm.requestFaucet({ address, network: "base-sepolia", token: "usdc" })
The CDP faucet funds the same wallets the CDP x402 facilitator settles against — no separate faucet needed.