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)

• Node.js and npm, or Python and pip

• 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

Node.js

HTTP Clients (Axios/Fetch) Install x402-axios or x402-fetch:

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

MCP (Unofficial) This community package showcases how AI agents can use Model Context Protocol (MCP) with x402. We're working on enshrining an official MCP spec in x402 soon.

Install the required packages for MCP support:

npm install x402-mcp ai @modelcontextprotocol/sdk

Python

2. Create a Wallet Client

Create a Wallet Client

Node.js (viem)

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

Python (eth-account)

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

Node.js

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. Full example here

import { wrapFetchWithPayment, decodeXPaymentResponse } from "x402-fetch";
// other imports...

// wallet creation logic...

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

Axios

x402-mcp

Python

You can use either httpx or Requests to automatically handle 402 Payment Required responses and complete payment flows.

• Requests is a well-established library for synchronous HTTP requests. It is simple and ideal for straightforward, sequential workflows.

• HTTPX is a modern library that supports both synchronous and asynchronous (async) HTTP requests. Use HTTPX if you need high concurrency, advanced features like HTTP/2, or want to leverage Python’s async capabilities

Both support a simple and extensible approach. The simple returns a pre-configured client that handles payments automatically, while the extensible lets you use an existing session/client. The simple is covered here, while the extensible is in the README of the full examples linked below.

HTTPX

Full example here

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

Requests

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.