@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

``bash
npm install @perkos/util-x402-headers
`

Usage

`typescript
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

$3

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

$3

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

$3

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

$3

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

$3

| 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

$3

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

$3

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

$3

`typescript
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;
};
}
`

$3

`typescript
interface PaymentRequirementsHeader {
scheme: "exact" | "deferred";
network: string;
maxAmountRequired: string;
resource: string;
description?: string;
mimeType?: string;
payTo: string;
asset: string;
outputSchema?: string;
extra?: Record;
}
``

Related Packages

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

License

MIT