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-axios and x402-fetch helper packages 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)
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 installed
• A service that requires payment via x402

​

1. Install Dependencies

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 Wallet API (recommended) or viem.

import { CdpClient } from "@coinbase/cdp-sdk";
import { createWalletClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const cdp = new CdpClient();

const account = await cdp.evm.createAccount();

import { CdpClient } from "@coinbase/cdp-sdk";
import { createWalletClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const cdp = new CdpClient();

const account = await cdp.evm.createAccount();

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

​

3. Make Paid Requests Automatically

You can use either x402-fetch or x402-axios to automatically handle 402 Payment Required responses and complete payment flows.

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

​

4. Error Handling

Both x402-fetch and x402-axios 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 either x402-fetch or x402-axios
• Create a wallet client (using viem or CDP Wallet API)
• 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

For questions or support, join our Discord.