x402 Agent Starter

Starter template for AI agents that pay for x402-gated resources using Routex multi-chain routing.

What this does: Your agent calls an API. The API returns 402 Payment Required. Routex evaluates all configured blockchains, picks the cheapest, signs the payment, and your agent gets the resource. No manual chain selection. No overpaying.

Quick Start

# 1. Clone and install
git clone https://github.com/routexcc/x402-agent-starter.git
cd x402-agent-starter
pnpm install

# 2. Configure
cp .env.example .env
# Edit .env — add your agent wallet private key and receiving address

# 3. Run the test server (terminal 1)
pnpm server

# 4. Run the agent (terminal 2)
pnpm agent

What Happens

Agent                         Server                      Routex
  │                              │                           │
  │──── GET /weather ───────────>│                           │
  │<─── 402 + payment options ───│                           │
  │                              │                           │
  │──── payment requirements ──────────────────────────────>│
  │                              │    evaluate Base, Stellar, │
  │                              │    Solana, Polygon fees    │
  │<─── signed payload (cheapest chain) ────────────────────│
  │                              │                           │
  │──── GET /weather + payment ─>│                           │
  │<─── 200 + weather data ──────│                           │

Project Structure

src/
├── agent.ts     # AI agent that requests x402 resources via Routex
├── server.ts    # Local x402-gated test server (returns 402)
├── config.ts    # Environment validation — fails fast on bad config
└── signer.ts    # Non-custodial viem wallet signer for Routex

Adding More Chains

The starter uses Base Sepolia. To route across multiple chains, install additional adapters:

pnpm add @routexcc/chain-stellar @routexcc/chain-solana @routexcc/chain-polygon

Then add them to the adapters map in src/agent.ts:

import { createStellarAdapter } from '@routexcc/chain-stellar';
import { createSolanaAdapter } from '@routexcc/chain-solana';

const adapters = new Map([
  ['base', createBaseAdapter(viemClient, { testnet: true })],
  ['stellar', createStellarAdapter(stellarKeypair)],
  ['solana', createSolanaAdapter(solanaConnection)],
]);

Routex will automatically compare fees across all configured chains and pick the cheapest for each payment.

Routing Strategies

Change the strategy in src/agent.ts:

Strategy	Picks	Use When
'cheapest'	Lowest fee in USD	Cost-sensitive, high volume (default)
'fastest'	Lowest finality time	Real-time agents, time-critical
'balanced'	60% cost / 40% speed	General purpose
Custom scorer	Your logic	Domain-specific requirements

Security

• Non-custodial: Routex never accesses your private key directly. It calls signer.sign() and signer.signTypedData() only.
• Environment isolation: Private keys live in .env only, validated at startup, never logged.
• Dedicated wallet: Use a separate wallet for your agent. Fund it with only what it needs.
• BigInt arithmetic: All token amounts use bigint. No floating-point.
• Typed errors: Failed routes throw RouteExhaustedError with per-chain rejection reasons — never silent failures.

Connecting to Real x402 APIs

Replace X402_RESOURCE_URL in .env with any x402-enabled endpoint:

X402_RESOURCE_URL=https://some-x402-api.com/data

The agent will automatically handle the 402 → payment → resource flow.

Requirements

• Node.js >= 20
• pnpm (or npm/yarn)
• A funded testnet wallet with Base Sepolia USDC
• Base Sepolia RPC endpoint (free public RPC included by default)

Testnet USDC

Get Base Sepolia testnet USDC:

1. Get Sepolia ETH from a faucet (e.g., Alchemy Sepolia Faucet)
2. Bridge or mint USDC on Base Sepolia using the USDC faucet

Links

• Routex — Multi-chain router
• x402 Protocol
• Routex on npm
• x402 Documentation

License

MIT