Carson Roscoe d352574bd5
feat: add upto to typescript sdk (#1773)
* 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>
2026-03-25 16:10:04 -07:00
..
2026-03-01 12:22:24 +09:00
2025-08-18 16:16:58 -04:00
2025-04-25 12:05:40 -04:00

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 from x402-axios.
  • clients/fetch/ - Client using the x402-fetch wrapper around the native fetch API.
  • clients/cdp-sdk/ - Client that uses CDP Server Wallets as the signer with x402-axios.
  • clients/chainlink-vrf-nft/ - Example using Chainlink to mint a randomized NFT (see them on Opensea). Demonstrates verify/settle flow with x402-axios.

Agents

  • agent/ - Anthropic agent that pays via a Go proxy using x402-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 via x402-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 /verify and /settle.

Fullstack

  • fullstack/next/ - Next.js app demonstrating route protection with x402-next middleware.
  • 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 using x402-express middleware.
  • servers/hono/ - Hono server using x402-hono middleware.
  • 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.