Documentation Index
Fetch the complete documentation index at: https://docs.x402x.ai/llms.txt
Use this file to discover all available pages before exploring further.
Client examples
import { wrapFetchWithPayment } from "x402x-fetch";
import { parseEther } from "viem";
const fetchWithPay = wrapFetchWithPayment(fetch, walletClient, parseEther("0.01")); // Set max payment amount
const res = await fetchWithPay("https://api.example.com/premium", { method: "POST" });
Create client.ts, core logic:// 1. Create a wallet client
const client = createWalletClient({
account,
transport: http(),
chain: bsc,
});
// 2. Wrap fetch to support automatic payment
const fetchWithPay = wrapFetchWithPayment(
fetch,
walletClient.extend(publicActions),
parseEther("0.01")
);
// 3. Make the request (payment handled automatically)
const response = await fetchWithPay('http://localhost:3939/api/data', {
method: "POST",
});
import { createWalletClient, http, parseEther, publicActions } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402x-fetch";
import { bsc } from "viem/chains";
const PRIVATE_KEY='' // Wallet holding the USD1 token
const SERVER_URL='http://localhost:3939/api/data'
async function main() {
// Create wallet
const account = privateKeyToAccount(PRIVATE_KEY);
const client = createWalletClient({
account,
transport: http(),
chain: bsc,
});
// Create the paying fetch
const fetchWithPay = wrapFetchWithPayment(
fetch,
client.extend(publicActions),
parseEther("0.01")
);
// Call the paid API
const response = await fetchWithPay(SERVER_URL, {
method: "POST",
});
if (!response.ok) {
const error = await response.json();
console.error("❌ Error:", error);
return;
}
const data = await response.json();
console.log("✅ Received:", data);
}
main();
import { useX402Payment } from 'x402x-react';
import { useWalletClient } from 'wagmi';
function PaymentComponent() {
const { data: walletClient } = useWalletClient();
const { mutate, isPending, error, data } = useX402Payment({
targetUrl: 'https://api.example.com/resource',
walletClient,
});
return (
<button onClick={() => mutate()}>
{isPending ? 'Processing...' : 'Pay'}
</button>
);
}
Workflow
- Call the protected resource → receive 402
- Parse
accepts → choose one requirements
- Generate payment signature (Permit/EIP-3009/Permit2)
- Set
X-Payment and retry request → receive 200
Best practices
- Always set
maxValue to prevent overpayment
- For resources with multiple options, pass a selector to prioritize a token
- Print the payload and 402 body on failures for troubleshooting
FAQs
- Insufficient balance/expired/nonce error → re-sign as instructed
- Failures after network switch → ensure
network matches the requirements
Client SDK
API and examples
Payment Payload
Payload spec
Payment Types
Authorization options compared
Supported
Query support capabilities
