@perkos/util-x402-headers

x402 V2 HTTP headers utility for protocol compliance. Provides standardized response headers, CAIP-2 chain ID conversion, and receipt generation for x402 payment protocol.

Installation

npm install @perkos/util-x402-headers

Usage

import {
  generateRequestId,
  getVerifyHeaders,
  getSettleHeaders,
  createV2Receipt,
  buildWWWAuthenticateHeader,
  parseWWWAuthenticateHeader,
  networkToCAIP2,
  caip2ToNetwork,
  getChainId,
  getBlockExplorerTxUrl
} from '@perkos/util-x402-headers';

// Generate unique request ID for tracing
const requestId = generateRequestId();
// => "x402-m5k2j3f-a8b9c1"

// Convert network to CAIP-2 format
const caip2 = networkToCAIP2('base');
// => "eip155:8453"

// Convert CAIP-2 back to network name
const network = caip2ToNetwork('eip155:8453');
// => "base"

// Get headers for verify response
const verifyHeaders = getVerifyHeaders({
  requestId,
  network: 'base',
  scheme: 'exact',
  isValid: true,
  payer: '0x...'
});

// Get headers for settle response
const settleHeaders = getSettleHeaders({
  requestId,
  network: 'base',
  scheme: 'exact',
  success: true,
  payer: '0x...',
  transaction: '0x...'
});

// Create a V2 receipt
const receipt = createV2Receipt({
  requestId,
  network: 'base',
  scheme: 'exact',
  success: true,
  payer: '0x...',
  transaction: '0x...',
  amount: '1000000',
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
});

// Build WWW-Authenticate header for 402 responses
const wwwAuth = buildWWWAuthenticateHeader({
  scheme: 'exact',
  network: 'base',
  maxAmountRequired: '1000000',
  resource: '/api/service',
  payTo: '0x...',
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
});
// => 'x402 scheme="exact", network="eip155:8453", maxAmountRequired="1000000", ...'

// Parse WWW-Authenticate header
const parsed = parseWWWAuthenticateHeader(wwwAuth);

API Reference

Request ID

| Function | Description | |----------|-------------| | generateRequestId() | Generate unique request ID for tracing x402 requests |

Chain/Network Utilities

| Function | Description | |----------|-------------| | getChainId(network) | Get chain ID from network name | | networkToCAIP2(network) | Convert network name to CAIP-2 format (eip155:chainId) | | caip2ToNetwork(caip2) | Convert CAIP-2 format back to network name | | getBlockExplorerTxUrl(network, txHash) | Get block explorer URL for transaction |

HTTP Headers

| Function | Description | |----------|-------------| | getBaseHeaders() | Base V2 headers for all x402 responses | | getVerifyHeaders(params) | Headers for verify responses | | getSettleHeaders(params) | Headers for settle responses |

Payment Headers

| Function | Description | |----------|-------------| | buildWWWAuthenticateHeader(requirements) | Build WWW-Authenticate header for 402 responses | | parseWWWAuthenticateHeader(header) | Parse WWW-Authenticate header value |

Receipt

| Function | Description | |----------|-------------| | createV2Receipt(params) | Create a V2 receipt for settle responses |

Supported Networks

| Network | Chain ID | CAIP-2 | |---------|----------|--------| | Avalanche | 43114 | eip155:43114 | | Avalanche Fuji | 43113 | eip155:43113 | | Base | 8453 | eip155:8453 | | Base Sepolia | 84532 | eip155:84532 | | Celo | 42220 | eip155:42220 | | Celo Sepolia | 11142220 | eip155:11142220 | | Ethereum | 1 | eip155:1 | | Sepolia | 11155111 | eip155:11155111 | | Polygon | 137 | eip155:137 | | Polygon Amoy | 80002 | eip155:80002 | | Arbitrum | 42161 | eip155:42161 | | Arbitrum Sepolia | 421614 | eip155:421614 | | Optimism | 10 | eip155:10 | | Optimism Sepolia | 11155420 | eip155:11155420 | | Monad | 10142 | eip155:10142 | | Monad Testnet | 10143 | eip155:10143 |

Types

VerifyHeadersParams

interface VerifyHeadersParams {
  requestId: string;
  network: string;
  scheme: "exact" | "deferred";
  isValid: boolean;
  payer?: string | null;
}

SettleHeadersParams

interface SettleHeadersParams {
  requestId: string;
  network: string;
  scheme: "exact" | "deferred";
  success: boolean;
  payer?: string | null;
  transaction?: string | null;
}

V2Receipt

interface V2Receipt {
  version: "2.0.0";
  requestId: string;
  timestamp: string;
  network: {
    name: string;
    chainId: number | null;
    caip2: string | null;
  };
  payment: {
    scheme: "exact" | "deferred";
    payer: string | null;
    amount?: string;
    asset?: string;
  };
  settlement: {
    success: boolean;
    transaction: string | null;
    blockExplorer?: string | null;
  };
}

PaymentRequirementsHeader

interface PaymentRequirementsHeader {
  scheme: "exact" | "deferred";
  network: string;
  maxAmountRequired: string;
  resource: string;
  description?: string;
  mimeType?: string;
  payTo: string;
  asset: string;
  outputSchema?: string;
  extra?: Record<string, unknown>;
}

Related Packages

• @perkos/types-x402 - Core x402 types
• @perkos/util-chains - Chain utilities
• @perkos/service-x402 - x402 service orchestrator

License

MIT