@fastxyz/x402-types

Shared types and utilities for the x402 HTTP Payment Protocol. Zero runtime dependencies.

This package provides the canonical type definitions used across @fastxyz/x402-client, @fastxyz/x402-server, and @fastxyz/x402-facilitator.

Release 1 adds local v2 types, PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE constants, known legacy-to-CAIP network mappings, and fromV2 / toV2 converters. Existing internals remain v1-shaped behind these adapters; the client answers in the version requested by the seller. Original v2 offers are preserved for exact echoing rather than reconstructed from legacy fields.

The native envelope validator is deliberately whole-envelope and known-only: all offers must use exact and mapped Fast/EVM networks. An unsupported alternative rejects the entire envelope, including supported alternatives. Capability-filtered mixed-envelope negotiation is outside Release 1.

Use Cases

Use this package when you need to reference x402 payment types (PaymentRequirement, PaymentPayload, VerifyResponse, etc.), define network configurations (EvmChainConfig, FastNetworkConfig), parse price strings into raw token units, encode/decode base64 JSON payloads for X-PAYMENT headers, or determine network type from a network name string.

Out of scope: making payments → use @fastxyz/x402-client; protecting API routes → use @fastxyz/x402-server; verifying/settling payments on the network → use @fastxyz/x402-facilitator.

Installation

pnpm add @fastxyz/x402-types

Types

Payment Types

| Type | Description | | ---------------------- | ------------------------------------------------------------- | | PaymentRequirement | Payment requirement returned in a 402 response | | PaymentPayload | Decoded X-PAYMENT header payload | | FastPayload | Fast transaction certificate payload | | EvmPayload | EVM EIP-3009 authorization payload | | VerifyResponse | Facilitator verify result | | SettleResponse | Facilitator settle result | | SupportedPaymentKind | Facilitator /supported descriptor | | NetworkType | "evm" \| "fast" \| "svm" (SVM = Solana VM, forward-looking) |

Network Config Types

| Type | Description | | ------------------- | --------------------------------------------------------------------------------------- | | EvmChainConfig | EVM chain config: chainId, rpcUrl, usdcAddress, optional usdcName/usdcVersion | | FastNetworkConfig | Fast network config: rpcUrl, tokenId, networkId, committeePublicKeys |

Utilities

parsePrice(price, decimals?)

Parse human-readable price strings into raw token units (default 6 decimals for USDC).

import { parsePrice } from '@fastxyz/x402-types';

parsePrice('$0.10'); // "100000"
parsePrice('0.1 USDC'); // "100000"
parsePrice('100000'); // "100000" (passthrough)

encodePayload(value) / decodePayload<T>(encoded)

Base64 JSON encoding/decoding for X-PAYMENT and X-PAYMENT-RESPONSE headers.

import { encodePayload, decodePayload } from '@fastxyz/x402-types';

const encoded = encodePayload({ x402Version: 1, scheme: 'exact', ... });
const decoded = decodePayload(encoded);

getNetworkType(network)

Determine network type from a network name string.

import { getNetworkType } from '@fastxyz/x402-types';

getNetworkType('arbitrum-sepolia'); // "evm"
getNetworkType('fast-testnet'); // "fast"

Common Pitfalls

1. Do not hardcode decimals — parsePrice defaults to 6 (USDC); pass explicitly if using other tokens.
2. Do not assume network names — use getNetworkType() to determine if a network is "evm" or "fast".
3. Do not import network config values from this package — this package only provides type definitions; actual config values are provided by the caller.

Design

• Zero runtime dependencies — pure type definitions and utility functions
• No hardcoded values — network config types define the shape; callers provide actual values
• Single source of truth — all x402 packages import types from here