Skip to main content
This guide walks you through how to use x402 to interact with services that require payment. By the end of this guide, you will be able to programmatically discover payment requirements, complete a payment, and access a paid resource. The x402 helper packages for various languages greatly simplify your integration with x402. You’ll be able to automatically detect payment challenges, authorize payments onchain, and retry requests — all with minimal code. The packages will automatically trigger the following flow:
  1. Makes the initial request (if using Fetch) or intercepts the initial request (if using Axios/HTTPX/Requests)
  2. If a 402 response is received, parses the payment requirements
  3. Verifies the payment amount is within the allowed maximum
  4. Creates a payment header using the provided wallet client
  5. Retries the request with the payment header

​
Prerequisites

Before you begin, ensure you have:
  • A crypto wallet with USDC (any EVM-compatible wallet, e.g., CDP Wallet, AgentKit)
  • Node.js and npm, or Python and pip
  • A service that requires payment via x402
We have pre-configured examples available in our repo, including examples for fetch, Axios, and MCP.

​
1. Install Dependencies

  • Node.js
  • Python
Install x402-axios or x402-fetch:
npm install x402-axios
# or
npm install x402-fetch

​
2. Create a Wallet Client

Create a wallet client using CDP’s Server Wallet (recommended) or a standalone wallet library (viem for EVM on Node.js, eth-account for EVM on Python, or SolanaKit for Solana support). First, create an account at cdp.coinbase.com and get the following API keys from the portal to store as environment variables: 
# store in .env or using the command `export <name>="secret-info"`
CDP_API_KEY_ID=your-api-key-id
CDP_API_KEY_SECRET=your-api-key-secret
CDP_WALLET_SECRET=your-wallet-secret
Then, install the required packages: 
npm install @coinbase/cdp-sdk dotenv
Finally, instantiate the CDP client as suggested by the Server Wallet Quickstart: 
import { CdpClient } from "@coinbase/cdp-sdk";
import { toAccount } from "viem/accounts";
import dotenv from "dotenv";

dotenv.config()

const cdp = new CdpClient();
const cdpAccount = await cdp.evm.createAccount();
const account = toAccount(cdpAccount);

​
Standalone Wallet Libraries

If you prefer to use your own wallet, you can use standalone libraries:

​
EVM

  • Node.js (viem)
  • Python (eth-account)
Install the required package:
npm install viem
Then instantiate the wallet account:
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

// Create a wallet client (using your private key)
const account = privateKeyToAccount("0xYourPrivateKey"); // we recommend using an environment variable for this

​
Solana (SVM)

Use SolanaKit to instantiate a signer: 
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// 64-byte base58 secret key (private + public)
const signer = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

​
3. Make Paid Requests Automatically

You can automatically handle 402 Payment Required responses and complete payment flows using the x402 helper packages.
  • Node.js
  • Python
You can use either x402-fetch or x402-axios:
  • x402-fetch
  • x402-axios
x402-fetch extends the native fetch API to handle 402 responses and payment headers for you. Full example here
import { wrapFetchWithPayment, decodeXPaymentResponse } from "x402-fetch";

const fetchWithPayment = wrapFetchWithPayment(fetch, account);

fetchWithPayment(url, { //url should be something like https://api.example.com/paid-endpoint
method: "GET",
})
.then(async response => {
    const body = await response.json();
    console.log(body);

    const paymentResponse = decodeXPaymentResponse(response.headers.get("x-payment-response")!);
    console.log(paymentResponse);
})
.catch(error => {
    console.error(error.response?.data?.error);
});
Features:
  • Automatically handles 402 Payment Required responses
  • Verifies payment and generates payment headers
  • Retries the request with proof of payment
  • Supports all standard fetch options

​
4. Discover Available Services (Optional)

Instead of hardcoding endpoints, you can use the x402 Bazaar to dynamically discover available services. This is especially powerful for building autonomous agents that can find and use new capabilities. See the full example here for Python and Node.js.
  • Node.js
  • Python
import { useFacilitator } from "x402/verify";
import { facilitator } from "@coinbase/x402";

// Get the list function from the facilitator
const { list } = useFacilitator(facilitator);

// Discover all available x402 services
const services = await list();
Learn more about service discovery in the x402 Bazaar documentation, including how to filter services, understand their schemas, and build agents that can autonomously discover new capabilities.

​
5. Error Handling

Clients will throw errors if:
  • The request configuration is missing
  • A payment has already been attempted for the request
  • There is an error creating the payment header

​
Summary

  • Install an x402 client package
  • Create a wallet client
  • Use the provided wrapper/interceptor to make paid API requests
  • (Optional) Use the x402 Bazaar to discover services dynamically
  • Payment flows are handled automatically for you

​
References:

For questions or support, join our Discord.
⌘I