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 with402 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 facilitator —
createCdpFacilitatorClient()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 signing —
account.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/x402subpath import required.
@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).
Spend controls
Spend controls are enforced client-side on anyx402Client. With CdpX402Client, pass
spendControls in the constructor (the SDK wires them internally); for a plain x402Client, call
applySpendControls(client, controls) directly.
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_capcumulative_capnetwork_not_allowedasset_not_allowedpayee_not_allowedamount_unparseableledger_capacity_exceededconfiguration_invalidalready_applied
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.
APPROACH=2). See the Quickstart for Sellers for Hono/Next.js
variants, payToConfig, mainnet setup, and discovery metadata.
CDP Facilitator
If you already run anx402ResourceServer (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.
APPROACH=1).
Direct signing
Every CDP account (EVM server account, EVM smart account, and Solana account) also exposessignX402Payment(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.
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 withclient.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" })
What to read next
- Quickstart for Buyers — pay for x402-protected APIs with a CDP wallet
- Quickstart for Sellers — gate your API and settle via the CDP facilitator
- MCP Server with x402 — pay for APIs from an MCP server
- x402 Bazaar — discover and list x402 services