@switchboard-xyz/x402-utils

Utilities for handling HTTP 402 Payment Required responses with the faremeter payment protocol.

Installation

pnpm add @switchboard-xyz/x402-utils

Usage

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);

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.

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

Derives the X-PAYMENT header that would be generated for a given request. Useful for debugging.

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

Extracts the x402 payment information from a 402 Payment Required response. This method makes a request expecting a 402 status code and returns the parsed JSON body containing the payment details.

const paymentInfo = await fetchManager.fetchX402Info(
  'https://api.example.com/data',
  { method: 'GET' }
);
console.log('Payment details:', paymentInfo);
// Returns:
// {
//   accepts: [
//     {
//       scheme: 'deferred',
//       network: 'solana',
//       resource: 'https://api.example.com/data',
//       amount: '1000000',
//       token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
//       recipient: '...'
//     }
//   ]
// }

Types

X402PaymentDetails

Interface representing the payment details returned in a 402 Payment Required response:

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