@switchboard-xyz/x402-utils

Utilities for handling HTTP 402 Payment Required responses with x402 v1 (faremeter) and x402 v2 (@x402/fetch).

Installation

pnpm add @switchboard-xyz/x402-utils

Usage (x402 v1)

import { X402FetchManager } from '@switchboard-xyz/x402-utils';
import { exact } from '@faremeter/payment-solana';
import { createLocalWallet } from '@faremeter/wallet-solana';

// Create a wallet and payment handler
const wallet = createLocalWallet();
const paymentHandler = exact({ wallet });

// Create the fetch manager
const fetchManager = new X402FetchManager(paymentHandler);

// Make a request - payments are handled automatically
const response = await fetchManager.fetch('https://api.example.com/data', {
  method: 'GET',
  headers: { 'Accept': 'application/json' }
});

const data = await response.json();
console.log(data);

Usage (x402 v2)

pnpm add @x402/fetch @x402/svm

import { x402Client } from '@x402/fetch';
import { ExactSvmScheme } from '@x402/svm/exact/client';
import { X402FetchManager } from '@switchboard-xyz/x402-utils';

const client = new x402Client().register(
  'solana:*',
  new ExactSvmScheme(/* your signer */)
);

const fetchManager = X402FetchManager.fromX402Client(client);
const response = await fetchManager.fetch('https://api.example.com/data', {
  method: 'GET',
  headers: { Accept: 'application/json' },
});

const paymentResponse = fetchManager.getPaymentSettleResponse(response);
console.log('Payment response:', paymentResponse);

API

X402FetchManager

A class that wraps the fetch API to automatically handle payment negotiations.

Constructor

new X402FetchManager(paymentHandler: client.PaymentHandler)

• paymentHandler: The payment handler to use for processing 402 responses

Methods

fetch(url: string, params?: RequestInit): Promise<Response>

Executes an HTTP request with automatic payment handling.

derivePaymentHeaders(url: string, params?: RequestInit): Promise<X402PaymentHeaders>

Derives the X-PAYMENT header that would be generated for a given request (x402 v1 only). Useful for debugging.

fetchX402Info(url: string, params?: RequestInit): Promise<X402PaymentDetails>

Extracts x402 payment information from a 402 Payment Required response. This method prefers the v2 PAYMENT-REQUIRED header and falls back to parsing the response body for v1.

const paymentInfo = await fetchManager.fetchX402Info(
  'https://api.example.com/data',
  { method: 'GET' }
);
console.log('Payment details:', paymentInfo);

getPaymentSettleResponse(response: Response): unknown | null

Parses the v2 PAYMENT-RESPONSE header when using an x402 v2 client.

Types

X402PaymentDetails

Interface representing payment details returned in a 402 Payment Required response (v1 or v2):

interface X402PaymentDetails {
  accepts: Array<{
    scheme: string;          // Payment scheme (e.g., "deferred")
    network: string;         // Blockchain network (e.g., "solana", "ethereum")
    resource: string;        // Resource URL being paid for
    amount?: string;         // Payment amount in smallest unit
    token?: string;          // Token contract/mint address
    recipient?: string;      // Payment recipient address
    extras?: Record<string, unknown>;  // Additional metadata
    [key: string]: unknown;  // Other fields
  }>;
}

License

MIT