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:
Makes the initial request (if using Fetch) or intercepts the initial request (if using Axios/HTTPX/Requests)
If a 402 response is received, parses the payment requirements
Verifies the payment amount is within the allowed maximum
Creates a payment header using the provided wallet client
First, create an account at cdp.coinbase.com and get the following API keys from the portal to store as environment variables:
Copy
Ask AI
# store in .env or using the command `export <name>="secret-info"`CDP_API_KEY_ID=your-api-key-idCDP_API_KEY_SECRET=your-api-key-secretCDP_WALLET_SECRET=your-wallet-secret
If you prefer to use your own wallet, you can use standalone libraries:
Install the required package:
Copy
Ask AI
npm install viem
Then instantiate the wallet account:
Copy
Ask AI
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
Install the required package:
Copy
Ask AI
npm install viem
Then instantiate the wallet account:
Copy
Ask AI
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
Install the required package:
Copy
Ask AI
pip install eth_account
Then instantiate the wallet account:
Copy
Ask AI
from eth_account import Accountaccount = Account.from_key("your_private_key") # we recommend using an environment variable for this
from x402.clients.httpx import x402HttpxClient# Other imports...# Wallet creation logic ...# Create client and make requestasync 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 requestasync 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 requestsession = x402_requests(account)response = session.get("https://api.example.com/protected-endpoint")print(response.content)