x402-avm-fetch

IMPORTANT: This package is temporary and works until the x402 Algorand specification and following implementation PR are reviewed and merged by Coinbase. Until then, this package contains X402 core protocol plus support for Algorand-specific types and utilities.

A utility package that extends the native fetch API to automatically handle 402 Payment Required responses using the x402 payment protocol. This package enables seamless integration of payment functionality into your applications when making HTTP requests.

Installation

npm install x402-avm-fetch

Quick Start

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-avm-fetch";
import { baseSepolia } from "viem/chains";

// Create a wallet client
const account = privateKeyToAccount("0xYourPrivateKey");
const client = createWalletClient({
  account,
  transport: http(),
  chain: baseSepolia,
});

// Wrap the fetch function with payment handling
const fetchWithPay = wrapFetchWithPayment(fetch, client);

// Make a request that may require payment
const response = await fetchWithPay("https://api.example.com/paid-endpoint", {
  method: "GET",
});

const data = await response.json();

API

wrapFetchWithPayment(fetch, walletClient, maxValue?, paymentRequirementsSelector?)

Wraps the native fetch API to handle 402 Payment Required responses automatically.

Parameters

• fetch: The fetch function to wrap (typically globalThis.fetch)
• walletClient: The wallet client used to sign payment messages (must implement the x402 wallet interface)
• maxValue: Optional maximum allowed payment amount in base units (defaults to 0.1 USDC)
• paymentRequirementsSelector: Optional function to select payment requirements from the response (defaults to selectPaymentRequirements)

Returns

A wrapped fetch function that automatically handles 402 responses by:

1. Making the initial request
2. If a 402 response is received, parsing the payment requirements
3. Verifying the payment amount is within the allowed maximum
4. Creating a payment header using the provided wallet client
5. Retrying the request with the payment header

Example

import { config } from "dotenv";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-avm-fetch";
import { baseSepolia } from "viem/chains";

config();

const { PRIVATE_KEY, API_URL } = process.env;

const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  account,
  transport: http(),
  chain: baseSepolia,
});

const fetchWithPay = wrapFetchWithPayment(fetch, client);

// Make a request to a paid API endpoint
fetchWithPay(API_URL, {
  method: "GET",
})
  .then(async response => {
    const data = await response.json();
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });

Algorand Signers

wrapFetchWithPayment also works with Algorand wallets. Provide any object that implements the x402 Algorand signer interface (address plus an async signTransactions function) and the helper automatically prefers Algorand (or Algorand Testnet) payment requirements when they exist.

import { wrapFetchWithPayment } from "x402-avm-fetch";

const algorandWallet = {
  address: account.address,
  signTransactions: async (transactions: Uint8Array[]) => {
    // Delegate to your Algorand wallet SDK (e.g. Pera, Defly) to sign the transactions
    return peraWallet.signTransactions([transactions]);
  },
};

const fetchWithPay = wrapFetchWithPayment(fetch, algorandWallet);