npm package: @perkos/types-x402
Description: TypeScript type definitions for x402 payment protocol
Author: PerkOS
Latest version: 1.1.1

# @perkos/types-x402

TypeScript type definitions for the x402 payment protocol. Provides comprehensive types for payment verification, settlement, ERC-8004 agent discovery, and V1/V2 specification compatibility.

## Installation

```bash
npm install @perkos/types-x402
```

## Overview

This package provides:

- **Core Protocol Types**: Payment requests, payloads, and responses
- **Scheme Types**: Exact (EIP-3009) and Deferred (EIP-712) payment schemes
- **Discovery Types**: ERC-8004 agent discovery and Bazaar service types
- **Type Guards**: Runtime type checking utilities
- **V1/V2 Compatibility**: Helper functions for both specification versions

## Usage

### Core Payment Types

```typescript
import type {
  PaymentPayload,
  PaymentRequirements,
  VerifyResponse,
  SettleResponse
} from '@perkos/types-x402';

const requirements: PaymentRequirements = {
  scheme: 'exact',
  network: 'base',
  amount: '1000000',            // V2 field
  maxAmountRequired: '1000000', // V1 field (backward compatible)
  resource: '/api/service',
  payTo: '0x...',
  maxTimeoutSeconds: 3600,
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
};
```

### Exact Scheme (EIP-3009)

```typescript
import type { ExactPayload, TransferAuthorization } from '@perkos/types-x402';

const authorization: TransferAuthorization = {
  from: '0x...payer',
  to: '0x...recipient',
  value: '1000000',
  validAfter: '0',
  validBefore: '1735689600',
  nonce: '0x...'
};

const payload: ExactPayload = {
  authorization,
  signature: '0x...'
};
```

### Deferred Scheme (EIP-712)

```typescript
import type { DeferredPayload, Voucher } from '@perkos/types-x402';

const voucher: Voucher = {
  id: '0x...',
  buyer: '0x...',
  seller: '0x...',
  valueAggregate: '5000000',
  asset: '0x...',
  timestamp: '1735689600',
  nonce: '1',
  escrow: '0x...',
  chainId: '8453'
};

const payload: DeferredPayload = {
  voucher,
  signature: '0x...'
};
```

### Type Guards

```typescript
import {
  isExactPayload,
  isDeferredPayload,
  isAddress,
  isHex,
  isCAIP2,
  isResourceObject
} from '@perkos/types-x402';

// Check payload type
if (isExactPayload(payload)) {
  console.log(payload.authorization.from);
} else if (isDeferredPayload(payload)) {
  console.log(payload.voucher.buyer);
}

// Validate addresses and hex strings
isAddress('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'); // true
isHex('0xabcdef'); // true

// Check network format (CAIP-2 vs legacy)
isCAIP2('eip155:84532');  // true
isCAIP2('base-sepolia');  // false

// Check resource format (V1 string vs V2 object)
isResourceObject({ url: '/api', description: 'API' }); // true
isResourceObject('/api');                               // false
```

### V1/V2 Compatibility Helpers

```typescript
import {
  getPaymentAmount,
  getResourceUrl,
  getResourceDescription,
  getResourceMimeType
} from '@perkos/types-x402';

// Works with both V1 (maxAmountRequired) and V2 (amount)
const amount = getPaymentAmount(requirements);

// Works with both V1 (string) and V2 (Resource object)
const url = getResourceUrl(requirements);
const description = getResourceDescription(requirements);
const mimeType = getResourceMimeType(requirements);
```

### ERC-8004 Agent Discovery

```typescript
import type { AgentInfo, AgentCard, PaymentMethod } from '@perkos/types-x402';

const agent: AgentInfo = {
  id: '0x...',
  name: 'My Agent',
  description: 'Payment processing agent',
  endpoint: 'https://api.example.com',
  capabilities: ['x402-payment-exact', 'x402-payment-deferred'],
  paymentMethods: [
    {
      scheme: 'exact',
      network: 'base',
      asset: '0x...',
      minAmount: '100000',
      maxAmount: '10000000'
    }
  ],
  reputation: {
    totalTransactions: 1000,
    successfulTransactions: 995,
    totalVolume: '1000000000000',
    averageRating: 4.8,
    lastUpdated: new Date()
  }
};
```

## API Reference

### Base Types

```typescript
// Ethereum address (0x + 40 hex chars)
export type Address = `0x${string}`;

// Hex string (0x prefix)
export type Hex = `0x${string}`;

// V2 Resource object
export interface Resource {
  url: string;
  description?: string;
  mimeType?: string;
}

// V2 Extensions for forward compatibility
export type Extensions = Record<string, unknown>;
```

### Payment Protocol Types

```typescript
// Verify request
export interface X402VerifyRequest {
  x402Version: number;
  paymentPayload: PaymentPayload;
  paymentRequirements: PaymentRequirements;
}

// Settle request (same as verify)
export interface X402SettleRequest extends X402VerifyRequest {}

// Payment payload
export interface PaymentPayload {
  x402Version: number;
  scheme: "exact" | "deferred";
  network: string;
  payload: ExactPayload | DeferredPayload;
  extensions?: Extensions;
}

// Payment requirements
export interface PaymentRequirements {
  scheme: "exact" | "deferred";
  network: string;              // Legacy or CAIP-2 format
  amount?: string;              // V2 spec field
  maxAmountRequired?: string;   // V1 legacy field
  resource: string | Resource;  // V1 string or V2 object
  description?: string;         // V1 compatibility
  mimeType?: string;            // V1 compatibility
  payTo: Address;
  maxTimeoutSeconds: number;
  asset: Address;
  extra?: DeferredExtra;
  extensions?: Extensions;
}

// Deferred scheme extra config
export interface DeferredExtra {
  type: "new" | "aggregation";
  escrow: Address;
  facilitator?: string;
}
```

### Exact Scheme Types (EIP-3009)

```typescript
export interface ExactPayload {
  signature: Hex;
  authorization: TransferAuthorization;
  extensions?: Extensions;
}

export interface TransferAuthorization {
  from: Address;
  to: Address;
  value: string;
  validAfter: string;
  validBefore: string;
  nonce: Hex;
}
```

### Deferred Scheme Types (EIP-712)

```typescript
export interface DeferredPayload {
  voucher: Voucher;
  signature: Hex;
  extensions?: Extensions;
}

export interface Voucher {
  id: Hex;
  buyer: Address;
  seller: Address;
  valueAggregate: bigint | string;
  asset: Address;
  timestamp: bigint | string;
  nonce: bigint | string;
  escrow: Address;
  chainId: bigint | string;
}

export interface StoredVoucher {
  id: Hex;
  voucher: Voucher;
  signature: Hex;
  buyer: Address;
  seller: Address;
  asset: Address;
  nonce: bigint;
  valueAggregate: bigint;
  timestamp: bigint;
  settled: boolean;
  settledTxHash?: Hex;
  createdAt: Date;
  updatedAt: Date;
}

export interface DeferredInfoResponse {
  enabled: boolean;
  escrowAddress: Address;
  network: string;
  chainId: number;
  thawPeriod: number;
  maxDeposit: string;
}
```

### Response Types

```typescript
export interface VerifyResponse {
  isValid: boolean;
  invalidReason: string | null;
  payer: Address | null;
  extensions?: Extensions;
}

export interface SettleResponse {
  success: boolean;
  errorReason?: string;
  payer?: Address | null;
  transaction?: Hex | null;
  network: string;
  extensions?: Extensions;
}

export interface SupportedResponse {
  kinds: Array<{
    scheme: "exact" | "deferred";
    network: string;
  }>;
  extensions?: Extensions;
}
```

### ERC-8004 Agent Discovery Types

```typescript
export interface AgentInfo {
  id: Address;
  name: string;
  description: string;
  endpoint: string;
  capabilities: string[];
  paymentMethods: PaymentMethod[];
  reputation?: ReputationScore;
}

export interface PaymentMethod {
  scheme: "exact" | "deferred";
  network: string;
  asset: Address;
  minAmount?: string;
  maxAmount?: string;
}

export interface ReputationScore {
  totalTransactions: number;
  successfulTransactions: number;
  totalVolume: string;
  averageRating: number;
  lastUpdated: Date;
}

export interface AgentCard {
  "@context": string;
  id: Address;
  type: "Agent";
  name: string;
  description: string;
  url: string;
  capabilities: string[];
  paymentMethods: PaymentMethod[];
  endpoints: {
    x402: string;
    discovery: string;
  };
}
```

### Bazaar Discovery Types

```typescript
export interface BazaarService {
  id: string;
  name: string;
  description: string;
  endpoint: string;
  category: string;
  pricing: ServicePricing;
  capabilities: string[];
  tags: string[];
}

export interface ServicePricing {
  scheme: "exact" | "deferred";
  network: string;
  asset: Address;
  amount: string;
  unit: "per-request" | "per-minute" | "per-hour" | "per-day";
}
```

### Well-Known Types

```typescript
export interface X402PaymentConfig {
  version: number;
  facilitator: string;
  supportedSchemes: Array<{
    scheme: "exact" | "deferred";
    network: string;
  }>;
  endpoints: {
    verify: string;
    settle: string;
    supported: string;
  };
}
```

### Type Guards

| Function | Description |
|----------|-------------|
| `isExactPayload(payload)` | Check if payload is exact scheme |
| `isDeferredPayload(payload)` | Check if payload is deferred scheme |
| `isAddress(value)` | Validate Ethereum address format |
| `isHex(value)` | Validate hex string format |
| `isCAIP2(network)` | Check if network is CAIP-2 format |
| `isResourceObject(resource)` | Check if resource is V2 object |

### V1/V2 Compatibility Helpers

| Function | Description |
|----------|-------------|
| `getPaymentAmount(requirements)` | Get amount (V2) or maxAmountRequired (V1) |
| `getResourceUrl(requirements)` | Get URL from string or Resource object |
| `getResourceDescription(requirements)` | Get description from V1 or V2 format |
| `getResourceMimeType(requirements)` | Get mimeType from V1 or V2 format |

## V1/V2 Specification Differences

| Field | V1 | V2 |
|-------|----|----|
| Amount | `maxAmountRequired` | `amount` |
| Resource | `string` (URL) | `Resource` object |
| Description | `description` field | `resource.description` |
| MIME Type | `mimeType` field | `resource.mimeType` |
| Network | Legacy format (`base-sepolia`) | CAIP-2 format (`eip155:84532`) |
| Extensions | Not supported | `extensions?: Extensions` |

## Related Packages

- [@perkos/util-chains](https://www.npmjs.com/package/@perkos/util-chains) - Chain utilities
- [@perkos/scheme-exact](https://www.npmjs.com/package/@perkos/scheme-exact) - Exact payment scheme
- [@perkos/scheme-deferred](https://www.npmjs.com/package/@perkos/scheme-deferred) - Deferred payment scheme
- [@perkos/service-x402](https://www.npmjs.com/package/@perkos/service-x402) - x402 service orchestrator

## License

MIT