x402 HTTP Client Reference

x402 HTTP Client Reference

Detailed API reference for @x402-avm/fetch, @x402-avm/axios, and @x402-avm/avm client packages.

Package: @x402-avm/fetch

Installation

npm install @x402-avm/fetch @x402-avm/avm algosdk

Exports

wrapFetchWithPayment

Wraps a standard fetch function with automatic 402 payment handling.

function wrapFetchWithPayment(
  fetch: typeof globalThis.fetch,
  client: x402Client | x402HTTPClient,
): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

Flow:

1. Makes the initial HTTP request normally
2. If the server responds with 402, parses payment requirements from the response
3. Selects a suitable payment method based on registered schemes
4. Creates a payment payload by signing a transaction group
5. Retries the request with the PAYMENT-SIGNATURE header
6. If the response is anything other than 402, returns it as-is

wrapFetchWithPaymentFromConfig

Config-based variant that creates the x402Client internally.

function wrapFetchWithPaymentFromConfig(
  fetch: typeof globalThis.fetch,
  config: x402ClientConfig,
): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

x402ClientConfig

interface x402ClientConfig {
  schemes: Array<{
    network: string;       // CAIP-2 identifier or wildcard ("algorand:*")
    client: SchemeNetworkClient;
  }>;
  policies?: PaymentPolicy[];
}

PaymentPolicy

type PaymentPolicy = (
  version: number,
  requirements: PaymentRequirements[],
) => PaymentRequirements[];

Policies are applied in registration order. Each policy receives the remaining requirements and returns a filtered/transformed list.

decodePaymentResponseHeader

function decodePaymentResponseHeader(header: string): any;

Decodes the PAYMENT-RESPONSE or X-PAYMENT-RESPONSE header returned by the server after settlement.

Package: @x402-avm/axios

Installation

npm install @x402-avm/axios @x402-avm/avm algosdk axios

Exports

wrapAxiosWithPayment

Adds a response interceptor that handles 402 responses by signing and submitting payment transactions.

function wrapAxiosWithPayment(
  axiosInstance: AxiosInstance,
  client: x402Client | x402HTTPClient,
): AxiosInstance;

Returns the same Axios instance (mutated with the interceptor). The interceptor:

• Catches 402 responses
• Parses payment requirements (headers for V2, body for V1)
• Creates payment payload via x402Client
• Marks the request with __is402Retry = true to prevent infinite loops
• Retries with PAYMENT-SIGNATURE header

wrapAxiosWithPaymentFromConfig

function wrapAxiosWithPaymentFromConfig(
  axiosInstance: AxiosInstance,
  config: x402ClientConfig,
): AxiosInstance;

Interceptor Behavior

Client Request --> Axios sends request --> Server Response
                                              |
                       Status != 402 -------> Return response normally
                       Status == 402 -------> Already retried? --> Reject
                                              |
                                              Parse PaymentRequired
                                              Create payment payload
                                              Retry with PAYMENT-SIGNATURE
                                              Return retried response

Key details:

• Single retry: Only retries once per 402
• Request mutation: Modifies original config and retries via axiosInstance.request()
• Concurrent requests: Each 402 is handled independently
• Interceptor order: Payment interceptor should be added last

Package: @x402-avm/avm

Installation

npm install @x402-avm/avm algosdk

Exports

ClientAvmSigner Interface

The interface that bridges wallets (browser or server) to the x402 payment system.

interface ClientAvmSigner {
  /** The Algorand address of the payer */
  address: string;

  /**
   * Sign one or more transactions in a group.
   * @param txns - Array of unsigned transaction bytes (msgpack)
   * @param indexesToSign - Optional indices of transactions to sign.
   *                        If omitted, sign all transactions.
   * @returns Array where signed transactions contain the signed blob,
   *          and skipped transactions are null
   */
  signTransactions(
    txns: Uint8Array[],
    indexesToSign?: number[],
  ): Promise<(Uint8Array | null)[]>;
}

Subpath: @x402-avm/avm/exact/client

registerExactAvmScheme

function registerExactAvmScheme(
  client: x402Client,
  config: AvmClientConfig,
): void;

AvmClientConfig

interface AvmClientConfig {
  /** The client signer implementation */
  signer: ClientAvmSigner;

  /** Optional Algod configuration */
  algodConfig?: {
    /** Algod URL (defaults to AlgoNode testnet/mainnet) */
    algodUrl?: string;
    /** Algod API token */
    algodToken?: string;
    /** Pre-configured Algodv2 client */
    algodClient?: algosdk.Algodv2;
  };

  /** Optional: restrict to specific networks */
  networks?: string[];
}

x402Client Class

Constructor

const client = new x402Client(selector?: PaymentRequirementsSelector);

Optional selector overrides default selection logic for choosing among payment requirements.

Methods

Lifecycle Hooks

BeforePaymentCreation:

client.onBeforePaymentCreation(async (context) => {
  // context.selectedRequirements - the chosen payment requirements
  // context.paymentRequired - full 402 response
  // Return { abort: true, reason: "..." } to cancel payment
});

AfterPaymentCreation:

client.onAfterPaymentCreation(async (context) => {
  // context.paymentPayload - the signed payload
  // context.paymentRequired - full 402 response
});

PaymentCreationFailure:

client.onPaymentCreationFailure(async (context) => {
  // context.error - the error that occurred
  // Return { recovered: true, payload: ... } to provide fallback
});

Environment Variables

Network Constants

Testing

Unit Testing a Client

import { x402Client } from "@x402-avm/fetch";
import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";

// Create a mock signer for testing
const mockSigner = {
  address: "TEST_ADDRESS_58_CHARS_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  signTransactions: async (txns: Uint8Array[], indexesToSign?: number[]) => {
    return txns.map((_, i) => {
      if (indexesToSign && !indexesToSign.includes(i)) return null;
      return new Uint8Array([0x80]); // mock signed bytes
    });
  },
};

const client = new x402Client();
registerExactAvmScheme(client, { signer: mockSigner });

Integration Testing with Real Transactions

# Set up environment
export AVM_PRIVATE_KEY="your-base64-key-here"

# Run with tsx
npx tsx client-test.ts https://api.example.com/paid-endpoint

Important Notes

• AVM_PRIVATE_KEY is a Base64-encoded 64-byte key. The first 32 bytes are the seed, the last 32 bytes are the public key.
• Address derivation always uses algosdk.encodeAddress(secretKey.slice(32)) -- the public key portion.
• The algorand:* wildcard in config-based setups matches any Algorand network (testnet or mainnet).
• Policies are composable and applied in order. An empty result from any policy means no payment options are available.
• The Axios interceptor modifies the instance in place and returns it. Do not create a new instance after wrapping.

External Resources

• x402-avm Examples Repository
• x402-avm Documentation
• @txnlab/use-wallet Documentation
• algosdk TypeScript Reference