x402-agent

Autonomous x402 payment handling for LLM applications. Available as both an MCP server and a CLI code generator.

Two Ways to Use

1️⃣ CLI Code Generator (New!)

Best for: Integrating x402 payments directly into your application's codebase.

Scaffold x402 payment handling code into your project:

npx x402-agent init

Automatically generates:

• x402-endpoints.json - Configure your x402 endpoints
• lib/x402/ - Payment utilities (logger, config, wallet, types)
• Framework-specific API routes (Vite, Next.js, or Express)

Supported frameworks: Vite, Next.js, Express, or framework-agnostic TypeScript utilities.

→ Jump to CLI usage

2️⃣ MCP Server

Best for: Using with Claude Desktop, Claude Code, or other MCP clients.

Add x402 payment capabilities to your MCP-compatible LLM client:

npx x402-agent

Exposes configured x402 endpoints as MCP tools for autonomous agent access.

→ Jump to MCP usage

Features

• Autonomous Payments: Automatic x402 payment handling using CDP embedded wallets
• Multiple Integration Modes: CLI code generator or MCP server
• Framework Support: Vite, Next.js, Express, or framework-agnostic
• Flexible Configuration: JSON-based endpoint configuration with environment variable support
• Security First: Trust model ensures only approved endpoints can be called
• Multi-Network Support: Works with Base, Base Sepolia, Ethereum, and Sepolia testnets
• Production Ready: Used in production applications with automatic payment retries

Prerequisites

• Node.js >= 18.0.0
• A CDP embedded wallet with USDC balance

CLI Code Generator

Quick Start

# Navigate to your project directory
cd my-ai-app

# Run the CLI to scaffold x402 payment handling
npx x402-agent init

# Edit the generated x402-endpoints.json to configure your endpoints
# Add your private key to .env
echo "PRIVATE_KEY=0x..." >> .env

# Install dependencies and start using x402 endpoints!
npm install

What Gets Generated

The CLI creates the following files in your project:

Framework-Agnostic Files (Always Created)

• x402-endpoints.json - Configuration file with example endpoints
• lib/x402/payment-logger.ts - Payment logging utilities with BaseScan links
• lib/x402/config.ts - Config loader with environment variable interpolation
• lib/x402/types.ts - TypeScript type definitions
• lib/x402/wallet.ts - Wallet setup and x402-fetch wrapper utilities

Framework-Specific API Routes

Vite (+ Vercel Functions):

• api/x402/proxy.ts - Generic proxy handler for x402 endpoints

Next.js (App Router):

• app/api/x402/[endpoint]/route.ts - Dynamic route handler

Express:

• routes/x402.ts - Express router with middleware

None (Framework-agnostic):

• Only the shared utilities above (no API routes)

CLI Options

init command (code generator)

npx x402-agent init [options]

Options:
  -f, --framework <type>  Specify framework (vite|nextjs|express|none)
  --auto-detect          Auto-detect framework from package.json (default)
  -o, --output-dir <path> Output directory (default: current directory)
  --skip-install         Skip automatic dependency installation
  -h, --help            Display help

serve command (MCP server)

npx x402-agent serve [options]

Options:
  -t, --transport <type>  Transport type: stdio or sse (default: stdio)
  -p, --port <number>    Port for SSE transport (default: 8000)
  --host <address>       Host address for SSE transport (default: 0.0.0.0)
  -h, --help            Display help

Examples:
  npx x402-agent serve                           # stdio mode (Claude Desktop)
  npx x402-agent serve --transport sse           # SSE mode on port 8000
  npx x402-agent serve --transport sse -p 3000   # SSE mode on port 3000

Examples

Vite + React Application

# Auto-detect Vite and generate appropriate files
cd my-vite-app
npx x402-agent init

# Result:
# ✅ x402-endpoints.json
# ✅ lib/x402/*.ts (utilities)
# ✅ api/x402/proxy.ts (Vercel Function handler)

Then use in your React components:

// Call x402 endpoint from your frontend
const response = await fetch('/api/x402/proxy', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    endpointId: 'minifetch_extract_metadata',
    params: { url: 'https://example.com' }
  })
});

const result = await response.json();
console.log('Data:', result.data);
console.log('Transaction:', result.txHash);
console.log('BaseScan:', `https://basescan.org/tx/${result.txHash}`);

Next.js Application

cd my-nextjs-app
npx x402-agent init --framework nextjs

# Result:
# ✅ x402-endpoints.json
# ✅ lib/x402/*.ts (utilities)
# ✅ app/api/x402/[endpoint]/route.ts (App Router dynamic route)

Use in Server Components or API routes:

// app/page.tsx
async function extractMetadata(url: string) {
  const response = await fetch('/api/x402/minifetch_extract_metadata', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url })
  });
  return response.json();
}

Express Application

cd my-express-app
npx x402-agent init --framework express

# Result:
# ✅ x402-endpoints.json
# ✅ lib/x402/*.ts (utilities)
# ✅ routes/x402.ts (Express router)

Mount the router in your Express app:

// server.ts
import express from 'express';
import x402Router from './routes/x402.js';

const app = express();
app.use(express.json());

// Mount x402 router
app.use('/api/x402', x402Router);

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

// Now call: POST /api/x402/minifetch_extract_metadata

Configuration

After running the CLI, edit x402-endpoints.json to configure your endpoints:

{
  "wallet": {
    "provider": "cdp-embedded",
    "network": "base",
    "privateKey": "${PRIVATE_KEY}"
  },
  "endpoints": [
    {
      "id": "minifetch_extract_metadata",
      "name": "Extract URL Metadata",
      "url": "https://minifetch.com/api/v1/x402/extract/url-metadata",
      "method": "GET",
      "description": "Fetch and extract HTML metadata from a URL",
      "parameters": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "URL to extract" }
        },
        "required": ["url"]
      },
      "estimatedCost": "$0.01",
      "trusted": true
    }
  ]
}

Set your private key in .env:

PRIVATE_KEY="0x..."

MCP Server Usage

The MCP server supports two transport modes:

1. stdio (default) - For local MCP clients like Claude Desktop
2. SSE (Server-Sent Events) - For HTTP-based remote MCP clients like OpenAI Responses API, ChatGPT Connectors, and deployed web apps

Transport Modes

Stdio Transport (Local)

Run locally for Claude Desktop or other local MCP clients:

npx x402-agent
# or explicitly:
npx x402-agent serve --transport stdio

SSE Transport (Remote HTTP Server)

Run as HTTP server for OpenAI, ChatGPT, and remote MCP clients:

npx x402-agent serve --transport sse --port 8000

Server will start at http://localhost:8000/sse/

Available endpoints:

• /sse - MCP SSE connection endpoint
• /message - MCP message endpoint
• /health - Health check
• / - Server info

Deploy to production:

See examples/vercel-deployment/ for deploying to Vercel, or use any Node.js hosting:

# Replit, Railway, etc.
npx x402-agent serve --transport sse --port 8000 --host 0.0.0.0

Then use with OpenAI Responses API:

const response = await openai.responses.create({
  model: 'gpt-4o',
  input: [{
    role: 'user',
    content: [{ type: 'input_text', text: 'Extract metadata from example.com' }]
  }],
  tools: [{
    type: 'mcp',
    server_url: 'https://your-x402-server.vercel.app/sse/',
    allowed_tools: ['minifetch_extract_metadata'],
    require_approval: 'never'
  }]
});

Or add to ChatGPT Connectors:

1. Go to ChatGPT Settings → Connectors
2. Add new MCP server: https://your-x402-server.vercel.app/sse/
3. ChatGPT will discover your x402 tools automatically

Prerequisites

• An MCP-compatible client (Claude Desktop, Claude Code, OpenAI, ChatGPT, etc.)

Installation

Global Installation

npm install -g @x402-agent/mcp-server

Or Use with npx

npx @x402-agent/mcp-server

Configuration

1. Create Configuration Directory

mkdir -p ~/.x402-agent

2. Create Endpoint Configuration

Create ~/.x402-agent/endpoints.json:

{
  "wallet": {
    "provider": "cdp-embedded",
    "network": "base",
    "privateKey": "${PRIVATE_KEY}"
  },
  "endpoints": [
    {
      "id": "minifetch_extract_metadata",
      "name": "Extract URL Metadata",
      "url": "https://minifetch.com/api/v1/x402/extract/url-metadata",
      "method": "GET",
      "description": "Fetch and extract HTML metadata from a specified URL. Returns all HTML meta tags, Open Graph tags, Twitter tags, headings, image tags, and response headers. Set includeResponseBody=true to return entire response body as a string. Useful for SEO and AI research projects.",
      "category": "web-scraping",
      "parameters": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL from which to extract HTML metadata"
          },
          "includeResponseBody": {
            "type": "string",
            "description": "If set to 'true', includes the full HTML response body as a string in the result"
          }
        },
        "required": ["url"]
      },
      "estimatedCost": "$0.01",
      "trusted": true
    }
  ]
}

See config/endpoints.example.json for a complete example with multiple endpoints.

3. Set Environment Variables

Create a .env file or set environment variables:

export PRIVATE_KEY="0x..."
export X402_CONFIG_PATH="~/.x402-agent/endpoints.json"  # Optional, defaults to this
export DEBUG="false"  # Set to "true" for debug logging

4. Configure Your MCP Client

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x402-agent": {
      "command": "npx",
      "args": ["-y", "@x402-agent/mcp-server"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "X402_CONFIG_PATH": "~/.x402-agent/endpoints.json"
      }
    }
  }
}

Claude Code

Edit ~/.claude/settings.json:

{
  "mcp": {
    "x402-agent": {
      "command": "npx @x402-agent/mcp-server",
      "env": {
        "PRIVATE_KEY": "0x...",
        "X402_CONFIG_PATH": "~/.x402-agent/endpoints.json"
      }
    }
  }
}

Codex CLI

Edit ~/.codex/config.toml:

[[mcpServers]]
name = "x402-agent"
command = "npx"
args = ["@x402-agent/mcp-server"]

[mcpServers.env]
PRIVATE_KEY = "0x..."
X402_CONFIG_PATH = "~/.x402-agent/endpoints.json"

Usage

Once configured, your LLM agent can autonomously use the endpoints:

User: "Extract metadata from https://example.com and tell me about the page"

Agent: [Calls minifetch_extract_metadata tool]
       [Payment automatically handled via x402]
       [Receives metadata and summarizes]

The agent will:

1. Discover available tools via tools/list
2. Call endpoints via tools/call
3. Handle 402 payment responses automatically
4. Return results to the user

Production Deployment

For Node.js Applications

Install the MCP SDK and integrate the x402 agent into your backend:

npm install @modelcontextprotocol/sdk

import { spawn } from 'child_process';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Start MCP server as a child process
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@x402-agent/mcp-server'],
  env: {
    PRIVATE_KEY: process.env.PRIVATE_KEY,
    X402_CONFIG_PATH: './x402-endpoints.json'
  }
});

const client = new Client({ name: 'my-app', version: '1.0.0' }, {});
await client.connect(transport);

// Call x402-protected endpoints
const result = await client.callTool({
  name: 'minifetch_extract_metadata',
  arguments: { url: 'https://example.com' }
});

console.log('Result:', result.content);
console.log('Transaction:', result.txHash);
console.log('BaseScan:', `https://basescan.org/tx/${result.txHash}`);

Configuration Paths

The server looks for endpoints.json in the following order:

1. X402_CONFIG_PATH environment variable (explicit path)
2. ./x402-endpoints.json (project root)
3. ./config/endpoints.json (config folder)
4. ~/.x402-agent/endpoints.json (user home, fallback)

Production Best Practices

When deploying to production:

1. Add x402-endpoints.json to your repo (without secrets - use ${PRIVATE_KEY} template)
2. Set PRIVATE_KEY as environment variable in your deployment platform
3. Run the MCP server as a child process from your backend
4. Monitor wallet balance and set up alerts for low USDC
5. Use separate wallets for dev/staging/prod environments

Configuration Reference

Wallet Configuration

| Field | Type | Description | Required | |-------|------|-------------|----------| | provider | string | Wallet provider (only "cdp-embedded" supported) | Yes | | network | string | Network: "base", "base-sepolia", "ethereum", "sepolia" | Yes | | privateKey | string | Private key (hex or ${ENV_VAR}) | Yes |

Endpoint Configuration

| Field | Type | Description | Required | |-------|------|-------------|----------| | id | string | Unique identifier (snake_case) | Yes | | name | string | Human-readable name | Yes | | url | string | HTTPS URL of x402 endpoint | Yes | | method | string | HTTP method (GET, POST, PUT, PATCH, DELETE) | Yes | | description | string | Tool description (min 20 chars) | Yes | | parameters | object | JSON Schema for parameters | Yes | | trusted | boolean | Allow autonomous execution | Yes | | category | string | Endpoint category | No | | estimatedCost | string | Estimated cost per call | No |

Environment Variables

• PRIVATE_KEY: Your CDP wallet private key (required)
• X402_CONFIG_PATH: Path to endpoints.json (default: ~/.x402-agent/endpoints.json)
• DEBUG: Enable debug logging (default: false)

Development

Build from Source

# Clone the repository
git clone https://github.com/yourusername/x402-agent.git
cd x402-agent

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Project Structure

x402-agent/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server setup
│   ├── handlers/
│   │   ├── listTools.ts      # tools/list handler
│   │   └── callTool.ts       # tools/call handler
│   ├── registry/
│   │   ├── types.ts          # TypeScript types
│   │   ├── EndpointRegistry.ts
│   │   └── validator.ts      # Config validation
│   ├── payment/
│   │   ├── WalletManager.ts  # CDP wallet
│   │   └── PaymentHandler.ts # x402 integration
│   └── utils/
│       ├── errors.ts         # Error classes
│       ├── logger.ts         # Logging
│       └── retry.ts          # Retry logic
├── config/
│   └── endpoints.example.json
└── package.json

Troubleshooting

Server Not Starting

• Check that Node.js >= 18.0.0 is installed: node --version
• Verify PRIVATE_KEY is set correctly
• Check configuration file syntax: cat ~/.x402-agent/endpoints.json | jq

Endpoints Not Appearing

• Restart your MCP client after configuration changes
• Check server logs for errors (set DEBUG=true)
• Verify trusted: true is set in endpoint config

Payment Failures

• Ensure wallet has sufficient USDC balance
• Check network matches endpoint requirements
• Verify private key has correct format (0x...)

Configuration Errors

• Validate JSON syntax
• Ensure all required fields are present
• Check endpoint URLs use HTTPS
• Verify parameter schemas are valid JSON Schema

Security

Trust Model

Only endpoints with "trusted": true can be called autonomously. This prevents:

• Unauthorized spending on unknown endpoints
• Malicious endpoint injection
• Unintended payment execution

Review endpoints carefully before setting trusted: true!

Private Key Safety

✅ DO:

• Use environment variables for private keys (${PRIVATE_KEY})
• Use separate wallets for dev/staging/prod
• Monitor wallet balance and set up alerts
• Keep private keys in secure secret management systems
• Rotate keys periodically

❌ DON'T:

• Commit private keys to git
• Hardcode private keys in endpoints.json
• Share wallets between different applications
• Use production wallets for testing

Network Security

• All endpoints must use HTTPS
• Configuration files should have restricted permissions: chmod 600 ~/.x402-agent/endpoints.json

Production Security Checklist

• [ ] PRIVATE_KEY set as environment variable (not in code)
• [ ] endpoints.json uses ${PRIVATE_KEY} template
• [ ] Wallet has sufficient USDC balance for expected usage
• [ ] Endpoints are marked trusted: true only after verification
• [ ] Monitor transaction logs for unexpected payments
• [ ] Set up alerts for low USDC balance
• [ ] Test on testnet (base-sepolia) before production
• [ ] Use separate wallets for different environments

License

Apache-2.0

Contributing

Contributions are welcome! Please open an issue or pull request.

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/x402-agent/issues
• Documentation: https://docs.cdp.coinbase.com/x402/

Related Projects

• x402 Protocol
• Coinbase Developer Platform
• Model Context Protocol

x402-agent