x402x - x402x-docs

Overview

x402x is the core package of the x402x protocol, extending the x402 core with foundational types for EIP-3009, EIP-2612, and Permit2, Zod schemas, EVM utilities, and verification logic. It’s typically used indirectly by higher-level packages (x402x-fetch / x402x-server / x402x-facilitator / x402x-detector), but can also be imported directly when you need custom orchestration.

Capabilities

Types and Zod schemas: PaymentRequirements, PaymentPayload, Response402, etc.
EVM utilities: EIP-2612 Permit, EIP-3009, and Permit2 signing and verification
Validation logic: amount/network/signature/nonce checks
Modular design: shared, schemes, client, verify, facilitator, types

Install

npm i x402x@beta

Modules and exports

import type { PaymentRequirements, PaymentPayload, Response402 } from "x402x/types";

Other common entry points:

// Shared EVM utilities
import { getChainId, getNetworkName } from "x402x/shared/evm";

// Scheme utilities (exact)
import { createExactPaymentRequirements, validateExactPayment } from "x402x/schemes";

// Verification utilities
import { verifyPermitSignature, verifyEIP3009Signature, verifyPermit2Signature } from "x402x/verify";

When to use directly

Import base types/utilities when you need custom verification or orchestration
When building a facilitator

Types and schemas (example)

// PaymentRequirements
interface PaymentRequirements {
  scheme: string;              // "exact"
  network: string;             // "bsc-testnet"
  maxAmountRequired: string;   // amount (wei)
  asset: string;               // token address
  paymentType?: string;        // permit/eip3009/permit2
  resource?: string;
  description?: string;
  mimeType?: string;
  maxTimeoutSeconds?: number;
  outputSchema?: Record<string, unknown>;
  extra?: Record<string, unknown>;
}

// Response402
interface Response402 {
  x402Version: number;           // 1
  accepts: PaymentRequirements[]; // list of acceptable payment requirements
  error?: string;
}

Zod validation:

import { PaymentRequirementsSchema, Response402Schema } from "x402x/types";

const validated = PaymentRequirementsSchema.parse(unknownData);
const safe = Response402Schema.safeParse(unknownResp);

Usage examples

Create a 402 response

import type { Response402, PaymentRequirements } from "x402x/types";

function create402Response(accepts: PaymentRequirements[], error?: string): Response402 {
  return { x402Version: 1, accepts, error };
}

EVM utilities

import { getChainId, getNetworkName } from "x402x/shared/evm";
const id = getChainId("bsc-testnet"); // 97
const name = getNetworkName(97);      // "bsc-testnet"

Best practices

Use Zod schemas to validate external inputs at runtime
Leverage type inference to reduce manual type maintenance
Import modules on demand to avoid bundling everything

Relationship to other packages

fetch: generates payment headers and retry logic; depends on core types
server: orchestrates creation/verification/settlement; depends on verification and types
facilitator: defines payment processing interfaces and return types
detector: depends on a small subset of EVM/type utilities

Resources

Source: https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x
Standards: EIP-2612, EIP-3009, Permit2

​Overview

​Capabilities

​Install

​Modules and exports

​When to use directly

​Types and schemas (example)

​Usage examples

​Create a 402 response

​EVM utilities

​Best practices

​Relationship to other packages

​Resources