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.

Prerequisites

Before you begin, ensure you have:

• A crypto wallet with USDC (any EVM-compatible wallet, e.g., CDP Wallet)

• Node.js and npm installed

• A service that requires payment via x402

Note We have pre-configured examples available in our repo, including examples for fetch, Axios, and MCP.

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 or viem:

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

CDP Wallet API

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

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.

Fetch

x402-fetch extends the native fetch API to handle 402 responses and payment headers for you.

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

Axios

x402-axios adds a payment interceptor to Axios, so your requests are retried with payment headers automatically.

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

Features:

• Automatically handles 402 Payment Required responses

• Retries requests with payment headers

• Exposes payment response headers

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.