API Reference

Comprehensive reference documentation for all T402 packages.

Facilitator API

Mechanism Packages

@t402/core @t402/evm @t402/svm @t402/ton @t402/tron @t402/near @t402/aptos @t402/tezos @t402/polkadot @t402/stacks @t402/cosmos @t402/btc @t402/erc8004 @t402/extensions

Server Middleware

@t402/express @t402/hono @t402/fastify @t402/next

Client Libraries

@t402/fetch @t402/axios

UI Components

@t402/paywall @t402/react @t402/vue

Tools

@t402/wdk @t402/cli

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
Payment-Required: scheme="exact";network="eip155:8453";amount="10000";...
Content-Type: application/json
 
{
  "error": "Payment required",
  "accepts": [...]
}

Payment Header

Clients include payment in the Payment-Signature header:

GET /api/resource HTTP/1.1
Payment-Signature: signature="0x...";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

Facilitator API