Skip to content

typescript

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

typescript

README.md

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.