Buyer Guide

Client examples

Minimal integration
Full example (Node + viem)
React example (wagmi + viem)

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

View full client code

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

Introduction

Quick Start

Concepts

Services

Support

Client examples

Workflow

Best practices

FAQs

Client SDK

Payment Payload

Payment Types

Supported

​Client examples

​Workflow

​Best practices

​FAQs

​Related

Client SDK

Payment Payload

Payment Types

Supported

Client examples

Workflow

Best practices

FAQs

Related