* feat(evm): add upto payment scheme TypeScript SDK Implement the upto payment scheme for EVM, enabling usage-based payments where a client authorizes a maximum amount via Permit2 and the server settles for the actual amount used (which may be less). Covers all three roles: - Client: creates Permit2 payloads with max authorized amount - Server: builds payment requirements, forces permit2 transfer method - Facilitator: verifies permitted >= required, settles actual usage, supports zero-settlement path for no-charge responses Key design decisions: - Permit2 only (no EIP-3009, per spec) - Shared Permit2 witness struct with exact scheme - Re-exports shared utilities from exact (approval helpers, extensions, RPC) - V2 protocol only Resolves: CDPAI-714 * chore(evm): add JSDoc descriptions and fix lint errors in upto SDK Add comprehensive JSDoc descriptions, @param, and @returns tags to all upto scheme files to satisfy eslint jsdoc rules. Remove unused imports in facilitator test file. * refactor(evm): extract shared permit2 helpers to reduce duplication between exact and upto facilitators * refactor(evm): consolidate client-side createPermit2Payload into shared helper * refactor(evm): extract shared trySignEip2612Permit and trySignErc20Approval from scheme classes * refactor(evm): split shared/permit2-helpers into permit2.ts and extensions.ts * test(evm): add upto server, register, and types tests; expand client and facilitator coverage Add 3 new test files (server.test.ts, register.test.ts, types.test.ts) covering upto-specific server behaviors (permit2 forcing, facilitator address injection, price parsing), registration helpers for all three roles, and type guard validation. Expand existing client and facilitator tests with additional edge cases. Also includes in-progress source changes: shared permit2 helper refactoring, upto facilitator hardening, spec clarifications, and defaultAssets extraction. * fix(evm): resolve lint errors for CI — add missing JSDoc descriptions and fix unused vars * fix(evm): address PR review — align upto verify flow with exact, update spec, remove createEvmClient * refactor(evm): move shared utils to shared/, remove upto register pattern - Move validateErc20ApprovalForPayment to shared/erc20approval.ts (was in exact/facilitator/, used by both exact and upto) - Move RPC utilities to shared/rpc.ts, rename types to drop Exact prefix (EvmSchemeConfig, EvmSchemeOptions, etc.) with deprecated aliases - Remove registerUptoEvmScheme from client, facilitator, and server (v1 legacy pattern not needed for v2-only upto scheme) - Backward-compat re-exports preserved at original paths * test(e2e): add upto payment scheme e2e test coverage Add full e2e test suite for the upto payment scheme mirroring exact permit2 coverage: direct settle, EIP-2612 gas sponsoring, and ERC-20 approval gas sponsoring endpoints. - Add 3 upto endpoints to Express e2e server with UptoEvmScheme - Register UptoEvmScheme in TypeScript facilitator - Register UptoEvmClientScheme in fetch and axios e2e clients - Add upto Permit2 approve/revoke cycle handling in test runner - Add upto entry points to @x402/evm tsup.config.ts - Update test.config.json files for all components * fix(evm): harden upto type guard, add time window validation, improve settlement comments - Add validAfter check to isUptoPermit2Payload for stricter exact/upto discrimination - Add deadline > validAfter guard in client permit2 payload creation - Default simulateInSettle to true for settlement re-verification - Expand settlement re-verification comment for reviewer clarity - Add no-register.ts comments explaining V1 compat is not needed for upto - Clarify e2e test config description for upto endpoint - Add tests for validAfter type guard and buildUptoPermit2SettleArgs * feat: added SettlementOverride * fix: examples lock * feat: Added upto to hono/next e2e tests * feat: update upto tests * feat: update tests to support fallback facilitator for non-SDK parity testing * fix: format/lint * fix: add linting to upto example --------- Co-authored-by: Fabrice Cheng <fabrice.cheng@coinbase.com>
X402 TypeScript Examples
This directory contains a collection of TypeScript examples demonstrating how to use the X402 protocol in various contexts. These examples are designed to work with the X402 npm packages and share a workspace with the main X402 packages.
Setup
Before running any examples, you need to install dependencies and build the packages:
# From the examples/typescript directory
pnpm install
pnpm build
Example Structure
The examples are organized into several categories:
Clients
Examples of different client implementations for interacting with X402 services:
clients/axios/- Axios client with x402 payment interceptor fromx402-axios.clients/fetch/- Client using thex402-fetchwrapper around the native fetch API.clients/cdp-sdk/- Client that uses CDP Server Wallets as the signer withx402-axios.clients/chainlink-vrf-nft/- Example using Chainlink to mint a randomized NFT (see them on Opensea). Demonstrates verify/settle flow withx402-axios.
Agents
agent/- Anthropic agent that pays via a Go proxy usingx402-fetch.dynamic_agent/- Agent that discovers tools dynamically and pays per-request using x402.
Discovery
discovery/- Uses the facilitator to list available x402-protected resources (Bazaar).
MCP
mcp/- MCP server that makes paid API requests viax402-axios(Claude Desktop compatible).mcp-embedded-wallet/- Electron-based MCP server with an embedded wallet that signs requests via IPC.
Facilitator
facilitator/- Example implementation of an x402 payment facilitator exposing/verifyand/settle.
Fullstack
fullstack/next/- Next.js app demonstrating route protection withx402-nextmiddleware.fullstack/mainnet/- Next.js app configured for Base mainnet using the Coinbase hosted facilitator.fullstack/next-advanced/- [WIP] Deep Next.js integration using a paywall + session cookie after verify/settle.fullstack/browser-wallet-example/- Browser wallet template: Hono server + React client with session and one-time payments.fullstack/farcaster-miniapp/- Farcaster Mini App template with x402-protected APIs using MiniKit.fullstack/auth_based_pricing/- SIWE + JWT with conditional pricing ($0.01 with JWT vs $0.10 without) using x402.
Servers
Examples of different server implementations:
servers/express/- Express.js server usingx402-expressmiddleware.servers/hono/- Hono server usingx402-honomiddleware.servers/advanced/- Express server without middleware: delayed settlement, dynamic pricing, multiple requirements.servers/mainnet/- Server example for accepting real USDC on Base mainnet using the Coinbase hosted facilitator.
Running Examples
Each example directory contains its own README with specific instructions for running that example. Navigate to the desired example directory and follow its instructions.
Development
This workspace uses:
- pnpm for package management
- Turborepo for monorepo management
- TypeScript for type safety
The examples are designed to work with the main X402 packages, so they must be built before running any examples.
A note on private keys
The examples in this folder commonly use private keys to sign messages. Never put a private key with mainnet funds in a .env file. This can result in keys getting checked into codebases and being drained.
There are many ways to generate a keypair to use exclusively for development, one way is via foundry:
# install foundry
curl -L https://foundry.paradigm.xyz | bash
# generate a new wallet
cast w new
You can fund your new wallet on most networks via the testnet CDP Faucet, simply provide the address generated by cast.