API Reference

Complete API documentation for T402 packages.

Packages

Package	Description
@t402/core	Protocol types, HTTP utilities, client/server framework
@t402/evm	EVM chains with EIP-3009, ERC-4337, and LayerZero bridge
@t402/svm	Solana blockchain with SPL token transfers
@t402/ton	TON blockchain with Jetton transfers
@t402/tron	TRON blockchain with TRC-20 tokens
@t402/wdk	Tether WDK integration for self-custodial wallets

Architecture

T402 follows a three-component architecture:

┌─────────┐     ┌─────────────┐     ┌─────────────┐
│ Client  │────▶│ Facilitator │────▶│   Server    │
└─────────┘     └─────────────┘     └─────────────┘
     │                 │                   │
     └─────── Payment Authorization ───────┘

Client

The client initiates payments by signing authorization messages:

import { ExactEvmScheme } from '@t402/evm';
 
const scheme = ExactEvmScheme.client({
  signer: myWalletSigner,
  network: 'eip155:8453' // Base
});

Facilitator

The facilitator validates payments and executes on-chain transfers:

import { ExactEvmScheme } from '@t402/evm';
 
const scheme = ExactEvmScheme.facilitator({
  signer: facilitatorSigner,
  rpcUrl: 'https://mainnet.base.org'
});

Server

The server defines payment requirements and verifies completion:

import { ExactEvmScheme } from '@t402/evm';
 
const scheme = ExactEvmScheme.server({
  rpcUrl: 'https://mainnet.base.org'
});

Common Types

PaymentRequirements

Defines what payment is required for a resource:

interface PaymentRequirements {
  scheme: string;           // Payment scheme (e.g., "exact")
  network: string;          // CAIP-2 network ID (e.g., "eip155:8453")
  amount: string;           // Amount in smallest units (e.g., "1000000" for 1 USDT)
  payTo: string;            // Recipient address
  asset?: string;           // Token address (optional, defaults to native USDT)
  maxTimeoutSeconds?: number; // Maximum time for payment validity
  extra?: Record<string, unknown>; // Mechanism-specific data
}

PaymentPayload

The payment authorization sent by the client:

interface PaymentPayload {
  t402Version: number;      // Protocol version (2)
  accepted: {               // The requirements being paid
    scheme: string;
    network: string;
    amount: string;
    payTo: string;
    asset?: string;
    extra?: Record<string, unknown>;
  };
  payload: Record<string, unknown>; // Scheme-specific payload
  resource?: {              // Resource metadata
    url: string;
    description: string;
    mimeType: string;
  };
}

HTTP Protocol

402 Response

When payment is required, servers return HTTP 402:

HTTP/1.1 402 Payment Required
X-Payment: {"t402Version":2,"accepts":[...]}
Content-Type: application/json
 
{
  "error": "Payment required",
  "accepts": [...]
}

Payment Header

Clients include payment in the X-Payment header:

GET /api/resource HTTP/1.1
X-Payment: {"t402Version":2,"accepted":{...},"payload":{...}}

Error Handling

All packages use consistent error types:

import { T402Error, PaymentError, ValidationError } from '@t402/core';
 
try {
  await client.fetch(url);
} catch (error) {
  if (error instanceof PaymentError) {
    console.log('Payment failed:', error.code);
  }
}

Error Codes

Code	Description
`INSUFFICIENT_BALANCE`	Not enough tokens for payment
`INVALID_SIGNATURE`	Payment signature verification failed
`EXPIRED_PAYMENT`	Payment authorization has expired
`NETWORK_MISMATCH`	Wrong blockchain network
`INVALID_RECIPIENT`	Invalid payment recipient address

@t402/core