npm package: @perkos/util-x402-headers
Description: x402 V2 HTTP headers utility for protocol compliance
Author: PerkOS
Latest version: 1.0.1

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

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

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

### SettleHeadersParams

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

### V2Receipt

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

### PaymentRequirementsHeader

```typescript
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](https://www.npmjs.com/package/@perkos/types-x402) - Core x402 types
- [@perkos/util-chains](https://www.npmjs.com/package/@perkos/util-chains) - Chain utilities
- [@perkos/service-x402](https://www.npmjs.com/package/@perkos/service-x402) - x402 service orchestrator

## License

MIT