Quickstart for Buyers

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

​

1. Install Dependencies

npm install x402-axios
# or
npm install x402-fetch

npm install x402-axios
# or
npm install x402-fetch

pip install x402

​

2. Create a Wallet Client

Create a wallet client using CDP’s Wallet API (recommended) or a standalone wallet library (viem for Node.js or eth-account for Python).

​

CDP Wallet API (Recommended)

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 Wallet API 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:

npm install viem

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

npm install viem

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

pip install eth_account

from eth_account import Account

account = Account.from_key("your_private_key") # we recommend using an environment variable for this

​

3. Make Paid Requests Automatically

You can automatically handle 402 Payment Required responses and complete payment flows using the x402 helper packages.

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);
});

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);
});

import { withPaymentInterceptor, decodeXPaymentResponse } from "x402-axios";
import axios from "axios";

// Create an Axios instance with payment handling
const api = withPaymentInterceptor(
axios.create({
    baseURL, // e.g. https://api.example.com
}),
account,
);

api
.get(endpointPath) // e.g. /paid-endpoint
.then(response => {
    console.log(response.data);

    const paymentResponse = decodeXPaymentResponse(response.headers["x-payment-response"]);
    console.log(paymentResponse);
})
.catch(error => {
    console.error(error.response?.data?.error);
});

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);
});

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);
});

import { withPaymentInterceptor, decodeXPaymentResponse } from "x402-axios";
import axios from "axios";

// Create an Axios instance with payment handling
const api = withPaymentInterceptor(
axios.create({
    baseURL, // e.g. https://api.example.com
}),
account,
);

api
.get(endpointPath) // e.g. /paid-endpoint
.then(response => {
    console.log(response.data);

    const paymentResponse = decodeXPaymentResponse(response.headers["x-payment-response"]);
    console.log(paymentResponse);
})
.catch(error => {
    console.error(error.response?.data?.error);
});

from x402.clients.httpx import x402HttpxClient
# Other imports...

# Wallet creation logic ...

# Create client and make request
async with x402HttpxClient(account=account, base_url="https://api.example.com") as client:
    response = await client.get("/protected-endpoint")
    print(await response.aread())

from x402.clients.httpx import x402HttpxClient
# Other imports...

# Wallet creation logic ...

# Create client and make request
async with x402HttpxClient(account=account, base_url="https://api.example.com") as client:
    response = await client.get("/protected-endpoint")
    print(await response.aread())

from x402.clients.requests import x402_requests
# Other imports...

# Wallet creation logic ...

# Create session and make request
session = x402_requests(account)
response = session.get("https://api.example.com/protected-endpoint")
print(response.content)

​

4. 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
• Payment flows are handled automatically for you

​

References:

• x402-fetch npm docs
• x402-axios npm docs
• x402 PyPi page

For questions or support, join our Discord.