x402

The X402 extension adds payment support to agents using the X402 Payment Required protocol. It enables agents to require and process payments for their services.

Installation

bun add @regent/x402

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { payments, paymentsFromEnv } from '@regent/x402';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(payments({ config: paymentsFromEnv() }))
  .build();

API Reference

payments(options?)

Creates the payments extension.

function payments(options?: {
  config?: PaymentsConfig | false;
  policies?: string;  // Path to payment-policies.json
}): Extension<{ payments?: PaymentsRuntime }>

PaymentsConfig

type PaymentsConfig = {
  payTo: string;                      // Recipient wallet address
  facilitatorUrl: string;             // Payment facilitator URL
  network: string;                    // Blockchain network (e.g., 'base')
  policyGroups?: PaymentPolicyGroup[];  // Payment policies
  storage?: PaymentStorageConfig;     // Storage backend config
};

paymentsFromEnv()

Configure payments from environment variables:

function paymentsFromEnv(overrides?: Partial<PaymentsConfig>): PaymentsConfig

Environment Variables:

Variable	Description
PAYMENTS_RECEIVABLE_ADDRESS	Wallet address for receiving payments
FACILITATOR_URL	Payment facilitator service URL
NETWORK	Blockchain network identifier

X402 Protocol Flow

1. Client makes HTTP request
   ↓
2. Server requires payment → 402 Payment Required
   ├─ X-Price: "1.5" (USD)
   ├─ X-Pay-To: "0x..."
   ├─ X-Network: "base"
   └─ X-Facilitator: "https://..."
   ↓
3. Client wraps request with payment signature
   ↓
4. Server validates payment, processes request
   ↓
5. Response includes X-PAYMENT-RESPONSE header

Payment Storage

Storage Options

type PaymentStorageConfig = {
  type?: 'sqlite' | 'postgres' | 'in-memory';
  sqlite?: { dbPath?: string };
  postgres?: { connectionString: string };
};

SQLite Storage (Default)

import { createSQLitePaymentStorage } from '@regent/x402';

const storage = createSQLitePaymentStorage('.data/payments.db');

PostgreSQL Storage

import { createPostgresPaymentStorage } from '@regent/x402';

const storage = createPostgresPaymentStorage(
  'postgresql://user:pass@host/dbname'
);

In-Memory Storage

import { createInMemoryPaymentStorage } from '@regent/x402';

const storage = createInMemoryPaymentStorage();

Policy Groups

Policy groups control payment limits and restrictions.

PaymentPolicyGroup

type PaymentPolicyGroup = {
  name: string;
  outgoingLimits?: OutgoingLimitsConfig;
  incomingLimits?: IncomingLimitsConfig;
  allowedRecipients?: string[];
  blockedRecipients?: string[];
  allowedSenders?: string[];
  blockedSenders?: string[];
  rateLimits?: {
    maxPayments: number;
    windowMs: number;
  };
};

Outgoing Limits

type OutgoingLimitsConfig = {
  global?: OutgoingLimit;
  perTarget?: Record<string, OutgoingLimit>;
  perEndpoint?: Record<string, OutgoingLimit>;
};

type OutgoingLimit = {
  maxPaymentUsd?: number;   // Max per single payment
  maxTotalUsd?: number;     // Max cumulative in window
  windowMs?: number;        // Time window in ms
};

Incoming Limits

type IncomingLimitsConfig = {
  global?: IncomingLimit;
  perSender?: Record<string, IncomingLimit>;
  perEndpoint?: Record<string, IncomingLimit>;
};

type IncomingLimit = {
  maxPaymentUsd?: number;
  maxTotalUsd?: number;
  windowMs?: number;
};

Policy Configuration File

Create payment-policies.json:

[
  {
    "name": "Daily Outgoing Limit",
    "outgoingLimits": {
      "global": {
        "maxPaymentUsd": 10.0,
        "maxTotalUsd": 1000.0,
        "windowMs": 86400000
      },
      "perTarget": {
        "https://agent.example.com": {
          "maxTotalUsd": 500.0
        }
      }
    },
    "allowedRecipients": ["https://trusted.example.com"],
    "rateLimits": {
      "maxPayments": 100,
      "windowMs": 3600000
    }
  }
]

Load policies:

import { policiesFromConfig } from '@regent/x402';

const policies = policiesFromConfig('./payment-policies.json');

Entrypoint Pricing

Setting Prices

agent.entrypoints.add({
  key: 'premium-analyze',
  price: {
    invoke: '0.10',   // $0.10 per invocation
    stream: '0.05',   // $0.05 per stream
  },
  async handler({ input }) {
    return { output: { result: 'analyzed' } };
  },
});

Price Resolution

import { resolvePrice } from '@regent/x402';

const price = resolvePrice(entrypoint, agent.payments?.config, 'invoke');
// Returns string like "0.10" or null if free/undefined

X402 Fetch

Creating X402-Enabled Fetch

import { createX402Fetch, accountFromPrivateKey } from '@regent/x402';

const account = accountFromPrivateKey('0x...');
const x402Fetch = createX402Fetch({ account });

// Use like regular fetch - payments handled automatically
const response = await x402Fetch('https://agent.example.com/entrypoints/analyze/invoke', {
  method: 'POST',
  body: JSON.stringify({ input: { text: 'Hello' } }),
});

Account from Private Key

import { accountFromPrivateKey } from '@regent/x402';

const account = accountFromPrivateKey('0x...');
// Returns viem Account with address and signing capabilities

Runtime Payment Context

import { createRuntimePaymentContext } from '@regent/x402';

const ctx = await createRuntimePaymentContext({
  runtime: agent,
  network: 'base',
  maxPaymentBaseUnits: 1000000n,  // 1 USDC
});

// Use the wrapped fetch
const response = await ctx.fetchWithPayment('https://...');

RuntimePaymentContext

type RuntimePaymentContext = {
  fetchWithPayment: FetchLike | null;
  signer: Signer | null;
  walletAddress: `0x${string}` | null;
  chainId: number | null;
};

X402-Enabled LLM Client

import { x402LLM } from '@regent/x402';

const llm = x402LLM({
  privateKey: '0x...',
  model: 'gpt-5',
  apiURL: 'https://api.example.com/v1',
});

const response = await llm.chat({
  messages: [{ role: 'user', content: 'Hello' }],
});

PaymentsRuntime

When the extension is used, agent.payments provides:

interface PaymentsRuntime {
  config: PaymentsConfig;
  isActive: boolean;
  paymentTracker?: PaymentTracker;
  rateLimiter?: RateLimiter;
  policyGroups?: PaymentPolicyGroup[];

  requirements(entrypoint: EntrypointDef, kind: 'invoke' | 'stream'): RuntimePaymentRequirement;
  activate(entrypoint: EntrypointDef): void;
  resolvePrice(entrypoint: EntrypointDef, which: 'invoke' | 'stream'): string | null;
  getFetchWithPayment(runtime: AgentRuntime, network?: string): Promise<FetchLike | null>;
}

Payment Tracker

interface PaymentTracker {
  checkOutgoingLimit(
    groupName: string,
    scope: string,
    maxTotalUsd: number,
    windowMs: number | undefined,
    requestedAmount: bigint
  ): Promise<{ allowed: boolean; reason?: string }>;

  checkIncomingLimit(
    groupName: string,
    scope: string,
    maxTotalUsd: number,
    windowMs: number | undefined,
    requestedAmount: bigint
  ): Promise<{ allowed: boolean; reason?: string }>;

  recordOutgoing(groupName: string, scope: string, amount: bigint): Promise<void>;
  recordIncoming(groupName: string, scope: string, amount: bigint): Promise<void>;
  getOutgoingTotal(groupName: string, scope: string, windowMs?: number): Promise<bigint>;
  getIncomingTotal(groupName: string, scope: string, windowMs?: number): Promise<bigint>;
}

Rate Limiter

interface RateLimiter {
  checkLimit(
    groupName: string,
    maxPayments: number,
    windowMs: number
  ): { allowed: boolean; reason?: string };

  recordPayment(groupName: string): void;
  getCurrentCount(groupName: string, windowMs: number): number;
}

HTTP Headers

402 Payment Required Response

Header	Description
X-Price	Payment amount in USD (e.g., "1.5")
X-Pay-To	Recipient wallet address
X-Network	Blockchain network
X-Facilitator	Payment facilitator URL

Successful Payment Response

Header	Description
X-PAYMENT-RESPONSE	Base64-encoded payment confirmation

Amount Units

All amounts use 6 decimal places (USDC standard):

1 USDC = 1,000,000 base units
$1.50 = 1,500,000 base units

Utility Functions

parsePriceAmount

import { parsePriceAmount } from '@regent/x402';

const amount = parsePriceAmount('1.5');
// Returns: 1500000n (bigint)

extractPayerAddress

import { extractPayerAddress } from '@regent/x402';

const payer = extractPayerAddress(paymentResponseHeader);
// Returns: "0x..." or undefined

validatePaymentsConfig

import { validatePaymentsConfig } from '@regent/x402';

validatePaymentsConfig(config, network, entrypointKey);
// Throws if invalid

Supported Networks

EVM Networks

• base, base-sepolia

• ethereum, sepolia

• optimism, arbitrum

• polygon

SVM Networks

• solana, solana-testnet

Exports

// Extension
export { payments } from '@regent/x402';

// Configuration
export { paymentsFromEnv, policiesFromConfig } from '@regent/x402';

// Storage
export {
  createSQLitePaymentStorage,
  createPostgresPaymentStorage,
  createInMemoryPaymentStorage,
} from '@regent/x402';

// X402 utilities
export {
  createX402Fetch,
  accountFromPrivateKey,
  createRuntimePaymentContext,
  x402LLM,
} from '@regent/x402';

// Price utilities
export {
  resolvePrice,
  parsePriceAmount,
  extractPayerAddress,
  validatePaymentsConfig,
} from '@regent/x402';

// Types
export type {
  PaymentsConfig,
  PaymentPolicyGroup,
  OutgoingLimitsConfig,
  IncomingLimitsConfig,
  PaymentStorageConfig,
  PaymentsRuntime,
  RuntimePaymentContext,
} from '@regent/x402';