x402 Agent Starter — AI Agent Payment Infrastructure on Base

Deploy a paid AI agent endpoint on Base in minutes. Built for autonomous agents that need monetizable infrastructure.

What it does

Your agent earns USDC on Base when callers pay via the x402 protocol. No merchant account. No Stripe. No custody. Just a server that speaks the x402 standard.

Endpoints

All endpoints are x402-payment-gated on Base Mainnet (eip155:8453). Payment goes to your configured PAY_TO_ADDRESS.

Live example

The server behind this repo is live at webcams-log-under-general.trycloudflare.com:

# Health check
curl https://your-tunnel-url.trycloudflare.com/health

# Try a paid call (returns 402 with payment instructions)
curl https://your-tunnel-url.trycloudflare.com/api/data

# Pay and call — step by step
# 1. Get 402 response with payment requirements
curl https://your-tunnel-url.trycloudflare.com/api/data
# 2. Pay USDC to 0x4226... via your Base wallet (MetaMask, Rabby, programmatic)
# 3. Retry with your transaction hash
curl -H "x402-response: YOUR_TX_HASH" \
  https://your-tunnel-url.trycloudflare.com/api/data

# For production MCP agents: use @x402/mcp for automatic payment lifecycle

Quick deploy

git clone https://github.com/forge-builder/x402-agent-starter.git
cd x402-agent-starter
npm install

# Set your payment address (the wallet that receives USDC)
export PAY_TO_ADDRESS=0xYourBaseAddress
export PORT=3000

node server.js

AI Agent Caller Example

See examples/x402-caller.js — a Node.js script that demonstrates the full x402 payment flow from an AI agent's perspective (discovery → parse → sign → pay → retry). Run it against any x402 endpoint:

PRIVATE_KEY=0x... ENDPOINT_URL=https://your-endpoint.com node examples/x402-caller.js

Without a private key it runs in simulation mode and walks through every step.

How x402 payments work

See docs/x402-payment-flow.md for the complete technical reference: two-step flow, header specs, payment lifecycle diagrams, and troubleshooting.

Architecture

• Server: Node.js + Express + x402 middleware
• Network: Base Mainnet (eip155:8453)
• Payment: x402 protocol — callers send USDC to your address, headers prove payment
• RPC: https://mainnet.base.org
• Persistence: yield-history.json for historical data

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as @x402/mcp Client
    participant Server as x402 Server
    participant Blockchain as Base (USDC)
    participant Facilitator as x402 Facilitator

    Agent->>MCP: callTool("x402_data")
    MCP->>Server: GET /api/data
    Server-->>MCP: 402 Payment Required
    MCP->>Agent: payment required
    Agent->>MCP: approve(payment)
    MCP->>Blockchain: sign EIP-712 permit
    Blockchain-->>MCP: permit signature
    MCP->>Blockchain: submit tx (pay USDC)
    Blockchain-->>MCP: tx hash
    MCP->>Server: GET /api/data (x402-response: tx_hash)
    Server->>Facilitator: settle payment
    Server-->>MCP: 200 OK + data
    MCP-->>Agent: tool result

Requirements

• Node.js 18+
• A Base wallet address to receive payments
• USDC on Base to test (or just call the live server above)

Replace this starter

Fork it, replace the endpoint logic with your agent's capabilities, and you have a monetizable agent.

Articles

Two DEV.do drafts explore the demand side and market context:

• content/devto-article-draft.md — Original framing: building a paid x402 endpoint
• content/devto-article-draft-V2.md — "AI-to-AI Payments on Base" — leads with the 480K+ Base agent market, ERC-8004 identity, and AI-to-AI payment framing

Or use the included LaunchAgent plist for persistent server management on macOS.

Ecosystem

x402 is a general payment protocol for any HTTP service. These projects use x402 for real economic activity:

Related Standards

• ERC-8004: AI Agent Identity — onchain agent registry
• x402 Protocol Spec — full protocol reference
• docs.x402.org — official documentation