@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

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

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)

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)

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

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

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

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

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

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

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)

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

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

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

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

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 - Chain utilities
• @perkos/scheme-exact - Exact payment scheme
• @perkos/scheme-deferred - Deferred payment scheme
• @perkos/service-x402 - x402 service orchestrator

License

MIT