Build X402 Client

Build an x402 client

Take the user from nothing to one successful paid API call: resolve a CDP-managed wallet, wrap their HTTP client so it answers 402 automatically, fund the wallet on testnet, verify with a 200.

Resolve the Decisions table below before writing any code, then read only the language subsection you resolved to in step 3. This file covers TypeScript and Python; reading both will blend them.

When not to use this skill

• The user's end users should pay from their own wallets. That is x402 payments with User Wallets, a browser flow, not this server-side one.
• The user wants an agent to spend money now, without writing code. Use the agentic-wallet pay-for-service skill, which drives the awal CLI. It is the nearest neighbour to this skill and the most likely mis-selection.
• The user is the one charging. Use the build-x402-server skill.
• The user needs to construct and sign a payment by hand (signX402Payment, custom retry logic). Out of scope here; see Client configuration.

Decisions

Resolve every row before writing code. Detect first; only ask when detection is ambiguous.

The network row is a hard rule, not a preference: never move the user to Base mainnet unless they ask for it in the current turn, because mainnet payments spend real USDC.

Steps

1. Confirm credentials

Before installing anything, check that the environment has all three of CDP_API_KEY_ID, CDP_API_KEY_SECRET, and CDP_WALLET_SECRET. The API key authenticates the caller to CDP; the wallet secret is what lets the SDK sign payments. Missing either one fails at runtime, and it is a worse experience to discover that three steps in. Send the user to API key authentication if they have no key yet. Also confirm the runtime: Node.js 22 or later, or Python 3.10 or later.

2. Install

Pick the dependencies matching the Decisions table. @x402/core, @x402/evm, @x402/svm, and @x402/extensions are optional peer dependencies of the CDP SDK, so they are not installed for you, and all four are needed even for an EVM-only integration because @coinbase/cdp-sdk/x402 imports them at module load.

For TypeScript, use the package manager already configured in the project. If none is configured, use npm. Install:

• fetch: @coinbase/cdp-sdk, @x402/core, @x402/evm, @x402/svm, @x402/extensions, and @x402/fetch
• axios: the same packages with @x402/axios instead of @x402/fetch, plus axios
• MCP: the same packages with @x402/mcp instead of @x402/fetch, plus @modelcontextprotocol/sdk

For Python, use the package manager already configured in the project. If none is configured, use pip. Install:

• async: cdp-sdk and x402[evm,svm,httpx]
• sync: cdp-sdk and x402[evm,svm,requests]

3. Write the client

Read only the subsection matching the language resolved above.

TypeScript

CdpX402Client is the whole point of the TypeScript path. It provisions the wallet, registers the payment schemes, and already satisfies the signer interface the x402 wrappers expect, so it drops into any of them unchanged.

import { CdpX402Client } from "@coinbase/cdp-sdk/x402";
import { wrapFetchWithPayment } from "@x402/fetch";

const client = new CdpX402Client({ environment: "development" });

// The wallet lives inside the client, so print the address to know what to fund.
const { evmAddress } = await client.getAddresses();
console.log(`Paying from ${evmAddress}`);

const fetchWithPayment = wrapFetchWithPayment(globalThis.fetch, client);
const response = await fetchWithPayment("https://x402.vercel.app/protected");
console.log(`HTTP ${response.status}`);

There is no key to store anywhere — that is the reason a developer reaches for CDP here, so say so rather than burying it.

Three things that break first:

• Top-level await needs ESM or an async main(). In a CommonJS project this is the first error.
• Omitting environment means Base mainnet and real USDC.
• getAddresses() also returns svmAddress for Solana. The field is svmAddress, not solanaAddress.

axios: same client object, different wrapper — wrapAxiosWithPayment(axios.create(), client) from @x402/axios, which returns a wrapped axios instance.

MCP: paying for tool calls rather than routes, with wrapMCPClientWithPayment(mcpClient, client) from @x402/mcp. See clients/mcp/simple.ts below.

Migration: swap whatever signer the existing x402Client holds for CdpX402Client; the call sites stay where they are. See x402DevMigration.ts below.