@fastxyz/x402-client

Client SDK for the x402 HTTP Payment Protocol. Automatically handles HTTP 402 Payment Required responses by signing and paying for content.

Supports:

• Fast networks — via wallet rpcUrl
• EVM networks — via EIP-3009 transferWithAuthorization
• Auto-bridge — Fast USDC → EVM USDC when EVM balance insufficient

Use Cases

• Pay for a 402-protected API endpoint
• Handle HTTP 402 Payment Required responses automatically
• Auto-bridge Fast USDC → EVM USDC for EVM payments
• Check Fast balance or bridge funds manually

Out of scope: Protecting API routes → @fastxyz/x402-server · Running a facilitator → @fastxyz/x402-facilitator · General wallet operations → @fastxyz/sdk

Installation

pnpm add @fastxyz/x402-client

Quick Start

Fast Payment

import { x402Pay } from '@fastxyz/x402-client';

const result = await x402Pay({
  url: 'https://api.example.com/premium',
  wallet: {
    type: 'fast',
    privateKey: '0x...',
    publicKey: '0x...',
    address: 'fast1...',
    rpcUrl: 'https://api.fast.xyz/proxy-rest',
  },
});

console.log(result.body); // Paid content

EVM Payment

import { x402Pay } from '@fastxyz/x402-client';

const result = await x402Pay({
  url: 'https://api.example.com/premium',
  wallet: {
    type: 'evm',
    privateKey: '0x...',
    address: '0x...',
  },
  evmNetworks: {
    'arbitrum-sepolia': {
      chainId: 421614,
      rpcUrl: 'https://sepolia-rollup.arbitrum.io/rpc',
      usdcAddress: '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d',
    },
  },
});

Auto-Bridge (Fast → EVM)

When both wallet types and a bridgeConfig are provided, the client will automatically bridge Fast USDC to EVM if the EVM wallet has insufficient balance.

interface BridgeConfig {
  rpcUrl: string;           // Fast network RPC URL
  fastBridgeAddress: string; // Fast address of the AllSet bridge contract
  relayerUrl: string;        // AllSet relayer URL
  crossSignUrl: string;      // AllSet cross-sign service URL
  tokenEvmAddress: string;   // USDC address on the EVM side (e.g., '0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d')
  tokenFastTokenId: string;  // USDC token ID on the Fast network (hex, no 0x)
  networkId: string;         // Fast network ID (e.g., 'fast:testnet')
}

const result = await x402Pay({
  url: 'https://api.example.com/premium',
  wallet: [fastWallet, evmWallet],
  evmNetworks: { ... },
  bridgeConfig: {
    rpcUrl: 'https://rpc.testnet.fast.co',
    fastBridgeAddress: 'fast1bridge...',
    relayerUrl: 'https://relayer.example.com',
    crossSignUrl: 'https://crosssign.example.com',
    tokenEvmAddress: '0x...',
    tokenFastTokenId: 'abc123...',
    networkId: 'fast:testnet',
  },
});

API

x402Pay(params: X402PayParams): Promise<X402PayResult>

Main entry point. Fetches the URL, and if a 402 is returned, handles payment automatically.

Parameters (X402PayParams):

| Field | Type | Required | Description | | -------------- | -------------------------------- | -------- | ----------------------------------------------- | | url | string | Yes | URL of the 402-protected resource | | method | string | No | HTTP method (default: GET) | | headers | Record<string, string> | No | Custom headers | | body | string | No | Request body | | wallet | Wallet \| Wallet[] | Yes | Wallet(s) for payment | | evmNetworks | Record<string, EvmChainConfig> | No* | EVM chain configs (*required for EVM payments) | | bridgeConfig | BridgeConfig | No | Bridge config for auto-bridge | | verbose | boolean | No | Enable verbose logging |

bridgeFastusdcToUsdc(params)

Manually bridge Fast USDC to EVM USDC using a single params object.

import { bridgeFastusdcToUsdc } from '@fastxyz/x402-client';

const result = await bridgeFastusdcToUsdc({
  fastWallet,
  evmReceiverAddress: evmWallet.address,
  amount: 1000000n,
  rpcUrl: bridgeConfig.rpcUrl,
  fastBridgeAddress: bridgeConfig.fastBridgeAddress,
  relayerUrl: bridgeConfig.relayerUrl,
  crossSignUrl: bridgeConfig.crossSignUrl,
  tokenEvmAddress: bridgeConfig.tokenEvmAddress,
  tokenFastTokenId: bridgeConfig.tokenFastTokenId,
  networkId: bridgeConfig.networkId,
});

console.log(result.txHash); // Bridge transaction hash

getFastBalance(wallet: FastWallet, options: { rpcUrl: string; tokenId: string }): Promise<bigint>

Get a token balance on the Fast network.

import { getFastBalance } from '@fastxyz/x402-client';

const balance = await getFastBalance(fastWallet, {
  rpcUrl: 'https://api.fast.xyz/proxy-rest',
  tokenId: 'abc123...',
});
console.log('Fast USDC balance:', balance); // bigint (smallest units)

Low-Level Utilities

parse402Response(response: Response): Promise<PaymentRequired>

Parse a raw HTTP 402 response into a typed PaymentRequired object. Throws if the response status is not 402.

import { parse402Response } from '@fastxyz/x402-client';

const paymentReq = await parse402Response(response);
console.log(paymentReq.accepts); // Array of accepted payment methods

buildPaymentHeader(payload: unknown): string

Build a base64-encoded X-PAYMENT header value from a payment payload object. Useful for manual payment flows where you construct the payload yourself.

import { buildPaymentHeader } from '@fastxyz/x402-client';

const header = buildPaymentHeader({
  x402Version: 1,
  scheme: 'exact',
  // ...payment payload fields
});
// Use as: headers['X-PAYMENT'] = header

parsePaymentHeader(header: string): unknown

Parse a base64-encoded X-PAYMENT header string back into a decoded object. Inverse of buildPaymentHeader.

import { parsePaymentHeader } from '@fastxyz/x402-client';

const payload = parsePaymentHeader('eyJ4NDAyVmVyc2lvbiI6MS...');

Common Pitfalls

1. DO NOT omit rpcUrl on FastWallet — it is required, not optional.
2. DO NOT omit evmNetworks when using an EVM wallet — the SDK has no hardcoded chains.
3. DO NOT forget bridgeConfig when using auto-bridge — it must include networkId.
4. DO NOT pass a single wallet when auto-bridge is needed — pass [fastWallet, evmWallet] as an array.

Design

• No hardcoded network configs — all chain/network info provided via evmNetworks parameter
• Wallet-type dispatch — automatically routes to Fast or EVM handler based on wallet.type
• Progressive enhancement — start with a single wallet, add auto-bridge later