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.

Python

There is no CdpX402Client in Python, so assemble the pieces by hand rather than hunting for a one-liner that does not exist.

import asyncio

from cdp import CdpClient
from cdp.evm_local_account import EvmLocalAccount
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import ExactEvmScheme


async def main() -> None:
    async with CdpClient() as cdp:
        account = await cdp.evm.get_or_create_account(name="x402-client-wallet-1")
        signer = EthAccountSigner(EvmLocalAccount(account))
        print(f"Paying from {signer.address}")  # this is the address to fund

        payment_client = x402Client()
        payment_client.register("eip155:84532", ExactEvmScheme(signer))

        async with x402HttpxClient(payment_client) as http:
            response = await http.get("https://x402.vercel.app/protected")
            await response.aread()

        print(f"HTTP {response.status_code}")


asyncio.run(main())

EvmLocalAccount and the x402 signer protocol declare sign_typed_data differently, and EthAccountSigner is what reconciles them. Writing the wrap explicitly is a readability choice rather than a requirement: ExactEvmScheme already auto-wraps anything that is an eth_account BaseAccount, which EvmLocalAccount is, so passing the account directly works too. Keep the explicit form so the adaptation is visible. A type checker may flag it, since EvmLocalAccount subclasses BaseAccount rather than LocalAccount; at runtime it is correct.

Three things that break first:

• CdpClient is an async context manager. Resolve the account inside async with.
• On the httpx path, await response.aread() before touching the body.
• "eip155:84532" is Base Sepolia. Changing it is a deliberate network change.

requests: the sync alternative for a project with no async entry point. x402_requests(client) from x402.http.clients is a function that returns a requests.Session, and it needs x402ClientSync rather than x402Client — mixing the two raises a TypeError.

MCP: see clients/mcp/simple.py below.

4. Fund the wallet

Run the client once. With no USDC it fails, and it prints the address to fund. Send Base Sepolia USDC there:

import { CdpClient } from "@coinbase/cdp-sdk";

await new CdpClient().evm.requestFaucet({
  address: evmAddress,
  network: "base-sepolia",
  token: "usdc",
});

await cdp.evm.request_faucet(address=signer.address, network="base-sepolia", token="usdc")

The CDP faucet funds the same wallets the CDP Facilitator settles against, so there is no second faucet to find. Wait for the transfer to confirm before re-running — requesting and paying in the same run fails on an empty balance.

5. Verify

Re-run. HTTP 200 is the success signal, and it proves the whole path: the payment was verified, settled onchain, and the protected resource came back. If the user has no endpoint of their own yet, https://x402.vercel.app/protected charges $0.01 on Base Sepolia.

Troubleshooting

Runnable examples

TypeScript, under https://github.com/coinbase/cdp-sdk/blob/main/examples/typescript/x402/clients/: payForApi.ts, payForApiWithAxios.ts, payForApiWithSpendControls.ts, x402DevMigration.ts, mcp/simple.ts.

Python, under https://github.com/coinbase/cdp-sdk/blob/main/examples/python/x402/clients/: pay_for_api.py, pay_for_api_with_requests.py, mcp/simple.py.

Beyond the first paid call

• Spend limits, allowlists, lifecycle hooks: Client configuration
• Finding services to pay for: Discover services
• Discovery and payment over MCP: Discover and pay over MCP
• Mainnet: drop environment: "development", fund with real USDC, and confirm with the user first