x402 API Server

![npm: MCP Server](https://www.npmjs.com/package/@x402-api/mcp-server) ![npm: ElizaOS Plugin](https://www.npmjs.com/package/@x402-api/elizaos-plugin) ![Listed on awesome-x402](https://github.com/xpaysh/awesome-x402)

Pay-per-call crypto/DeFi data API using HTTP 402 Payment Required. No API keys. No subscriptions. AI agents pay USDC on Base, per request.

  ██╗  ██╗██╗  ██╗ ██████╗ ██████╗
   ╚██╗██╔╝██║  ██║██╔═══██╗╚════██╗
    ╚███╔╝ ███████║██║   ██║ █████╔╝
    ██╔██╗ ╚════██║██║   ██║██╔═══╝
   ██╔╝ ██╗     ██║╚██████╔╝███████╗
   ╚═╝  ╚═╝     ╚═╝ ╚═════╝ ╚══════╝

🌐 Live at: https://x402-api.fly.dev 🤖 Agent Identity: #18763 on Base (ERC-8004) 📝 Blog Post: I Built a DeFi Data API Where AI Agents Pay Per Call

---

What Is This?

This is a DeFi/crypto data API server where payment is part of the HTTP protocol itself.

Every endpoint costs a small USDC micropayment — between 0.001 and 0.008 USDC (fractions of a cent). When a client hits a protected endpoint, the server responds with HTTP 402 Payment Required and precise payment instructions. The client pays, retries with proof, and gets data.

No accounts. No OAuth. No billing dashboard. Just: "this costs 0.003 USDC — pay here."

This model is designed for AI agents: autonomous software that needs to call APIs without a human reaching for a credit card. The agent holds a wallet, pays exactly what's needed, and moves on.

The stack:

x402 Protocol — HTTP 402-based micropayment standard by Coinbase
USDC on Base — L2 mainnet, sub-cent fees, instant finality
ERC-8004 — on-chain identity registration for AI agents
Express.js backend — straightforward, auditable, no framework magic

---

Endpoints

| Endpoint | Price | Description | |----------|-------|-------------| | GET /api/price-feed | 0.001 USDC | BTC/ETH/SOL prices + top 24h movers (live CoinGecko) | | GET /api/gas-tracker | 0.001 USDC | Multi-chain gas prices (ETH, Base, Polygon, Arbitrum) with speed tiers | | GET /api/dex-quotes | 0.002 USDC | Compare swap quotes across Uniswap, SushiSwap, 1inch | | GET /api/token-scanner | 0.003 USDC | Token security & risk analysis — rug-pull detection flags | | GET /api/whale-tracker | 0.005 USDC | Token holder concentration, Gini coefficient, whale alerts | | GET /api/yield-scanner | 0.005 USDC | Top DeFi yields across Aave, Compound, Morpho, Lido, Pendle + more | | GET /api/funding-rates | 0.008 USDC | Perp funding rates across 6 venues + arb ranking | | GET /api/wallet-profiler | 0.008 USDC | Wallet portfolio analysis, holdings, activity, risk profile | | GET /api/endpoints | Free | Machine-readable endpoint catalog | | GET /health | Free | Health check |

Query Parameters

| Endpoint | Parameter | Example | |----------|-----------|---------| | /api/dex-quotes | from, to, amount | ?from=ETH&to=USDC&amount=1.5 | | /api/token-scanner | token | ?token=PEPE or ?token=0x... | | /api/whale-tracker | token | ?token=ETH | | /api/yield-scanner | chain, min_tvl | ?chain=base&min_tvl=1000000 | | /api/funding-rates | asset | ?asset=BTC | | /api/wallet-profiler | address | ?address=0x... |

---

How x402 Works

The x402 protocol extends the long-forgotten HTTP 402 Payment Required status code into a machine-readable micropayment standard.

The Payment Flow

Step 1 — Initial request (no payment) ``http GET /api/price-feed HTTP/1.1 Host: x402-api.fly.dev ``

Step 2 — Server returns 402 ```http HTTP/1.1 402 Payment Required Content-Type: application/json

{ "x402Version": 1, "error": "Payment Required", "accepts": [{ "scheme": "exact", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x60264c480b67adb557efEd22Cf0e7ceA792DefB7", "maxAmountRequired": "1000", "resource": "https://x402-api.fly.dev/api/price-feed", "description": "Live crypto price feed", "extra": { "name": "USD Coin", "chainId": 8453, "supportedProofs": ["txHash"], "experimentalProofs": ["eip3009_transferWithAuthorization"] } }] } ```

Step 3 — Client pays and retries ``http GET /api/price-feed HTTP/1.1 Host: x402-api.fly.dev X-Payment: <base64-encoded payment proof> ``

Step 4 — Server verifies and responds ```http HTTP/1.1 200 OK X-Payment-Response: {"success":true,"txHash":"0x..."} Content-Type: application/json

{ "btc": 95420.12, "eth": 3241.88, ... } ```

Payment Verification

In the current repo, the production-ready payment proof path is:

Transaction hash — Confirms a submitted Base transaction contains a USDC transfer to the receiving address.

The repo also supports EIP-3009 transferWithAuthorization settlement when you configure one of these:

Direct settlement via X402_SETTLEMENT_PRIVATE_KEY — the server submits transferWithAuthorization on-chain and pays gas.
Custom facilitator settlement via X402_FACILITATOR_URL — the server forwards the signed authorization to your facilitator.

Without either of those configured, the deployment stays on the txHash payment proof path only.

Receiving wallet: 0x60264c480b67adb557efEd22Cf0e7ceA792DefB7 Network: Base mainnet (chain ID 8453) Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

---

Using with x402-fetch

x402-fetch is the official client library from Coinbase that handles the payment flow automatically. Drop it in as a fetch replacement.

Installation

npm install x402-fetch viem

Basic Usage

import { wrapFetchWithPayment } from 'x402-fetch';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

// Wrap fetch — payments handled automatically
const fetchWithPayment = wrapFetchWithPayment(fetch, walletClient);

// Just call the API — 402 is handled transparently
const response = await fetchWithPayment('https://x402-api.fly.dev/api/price-feed');
const data = await response.json();
console.log(data);

What `wrapFetchWithPayment` Does

Makes the initial request
If 402 → parses payment requirements
Signs the payment authorization (EIP-3009 transferWithAuthorization)
Retries the request with X-Payment header
Returns the successful response

Note: this is the standard x402 client flow. The current server repo also supports a simpler proof format where a client pays on-chain first, then sends a Base64 JSON X-Payment header like:

{ "txHash": "0x...", "payer": "0x..." }

Your wallet needs USDC on Base mainnet. You can bridge USDC from Ethereum to Base using the Base Bridge or buy directly on Coinbase.

---

ERC-8004 Identity

This API is registered as an AI agent on Base via ERC-8004 — the Ethereum standard for on-chain agent identity.

Agent ID: #18763 Registry contract: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 Network: Base mainnet

The registration includes:

Agent name and description
Service endpoints (web + x402)
x402 capability flag
Reputation-based trust signals

This lets discovery services, AI marketplaces, and other agents find and verify this API on-chain — no centralized registry required.

See the registration data: agent-registration.json

---

Integrations

MCP Server (Claude Desktop / Claude API)

The MCP (Model Context Protocol) server now lives in its own standalone repo:

GitHub: fernsugi/x402-api-mcp-server
npm: @x402-api/mcp-server

Quick setup:

# Run without payment (inspect mode)
npx @x402-api/mcp-server

# Run with auto-pay
X402_WALLET_PRIVATE_KEY=0x... npx @x402-api/mcp-server

Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "x402-api": {
      "command": "npx",
      "args": ["@x402-api/mcp-server"],
      "env": {
        "X402_WALLET_PRIVATE_KEY": "0x<your_key>"
      }
    }
  }
}

→ See the standalone MCP repo for full docs: x402-api-mcp-server README

ElizaOS Plugin

The elizaos-plugin/ directory contains an ElizaOS plugin that gives autonomous agents natural-language access to all 8 endpoints.

Install:

npm install @x402-api/elizaos-plugin

Register in your ElizaOS agent:

import { x402ApiPlugin } from '@x402-api/elizaos-plugin';

export const agent: Character = {
  name: 'DeFi Agent',
  plugins: [
    x402ApiPlugin({
      walletPrivateKey: process.env.X402_WALLET_PRIVATE_KEY,
    }),
  ],
};

The plugin adds 8 actions: GET_CRYPTO_PRICES, GET_GAS_PRICES, GET_DEX_QUOTES, SCAN_TOKEN, TRACK_WHALES, SCAN_YIELDS, GET_FUNDING_RATES, PROFILE_WALLET.

→ See elizaos-plugin/README.md for full docs.

---

Local Development

git clone https://github.com/sugi/x402-api-server
cd x402-api-server
cp .env.example .env   # defaults to development mode
npm install
npm run dev            # auto-reload on changes

In development mode (NODE_ENV=development), any non-empty X-PAYMENT header is accepted — no real payments needed for local testing.

# Get 402 response with payment instructions
curl -i http://localhost:4020/api/price-feed

# Test with mock payment (dev only)
curl http://localhost:4020/api/price-feed -H "X-Payment: test"

---

Architecture

src/
├── index.js                 # Express server + graceful shutdown
├── payment-config.js        # Settlement mode + proof support detection
├── middleware/
│   └── x402.js              # x402 payment gate middleware
├── routes/
│   ├── priceFeed.js         # /api/price-feed (live CoinGecko)
│   ├── gasTracker.js        # /api/gas-tracker (real RPC + mock)
│   ├── dexQuotes.js         # /api/dex-quotes
│   ├── tokenScanner.js      # /api/token-scanner
│   ├── whaleTracker.js      # /api/whale-tracker
│   ├── yieldScanner.js      # /api/yield-scanner
│   ├── fundingRates.js      # /api/funding-rates
│   └── walletProfiler.js    # /api/wallet-profiler
├── services/
│   └── verifier.js          # txHash verifier + EIP-3009 settlement
└── views/
    └── index.html           # Landing page

elizaos-plugin/              # @x402-api/elizaos-plugin

Standalone sibling repo:
x402-api-mcp-server/         # @x402-api/mcp-server

---

Deployment

Fly.io (recommended)

curl -L https://fly.io/install.sh | sh
fly auth login
./deploy.sh

Docker

docker compose up -d

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PAY_TO_ADDRESS | 0x60264c...DefB7 | USDC receiving wallet on Base | | PORT | 4020 | Server port | | NODE_ENV | development | Set production for real payment verification | | BASE_RPC_URL | https://mainnet.base.org | Base RPC URL | | X402_SETTLEMENT_MODE | auto | auto, direct, facilitator, or disabled | | X402_SETTLEMENT_PRIVATE_KEY | none | Sponsor key for direct transferWithAuthorization settlement | | X402_FACILITATOR_URL | none | Custom facilitator URL for EIP-3009 settlement | | X402_FACILITATOR_API_KEY | none | Optional bearer token for your facilitator |

---

Links

---

License

MIT

x402-api-server

x402 API Server

What Is This?

Endpoints

Query Parameters

How x402 Works

The Payment Flow

Payment Verification

Using with x402-fetch

Installation

Basic Usage

What `wrapFetchWithPayment` Does

ERC-8004 Identity

Integrations

MCP Server (Claude Desktop / Claude API)

ElizaOS Plugin

Local Development

Architecture

Deployment

Fly.io (recommended)

Docker

Environment Variables

Links

License

Score

Proud of your score? Add this badge to your README.

x402-api-server FAQ

How do I install x402-api-server?

Is x402-api-server an official MCP server?

Related MCP servers

Related guides

x402-api-server

x402 API Server

What Is This?

Endpoints

Query Parameters

How x402 Works

The Payment Flow

Payment Verification

Using with x402-fetch

Installation

Basic Usage

What wrapFetchWithPayment Does

ERC-8004 Identity

Integrations

MCP Server (Claude Desktop / Claude API)

ElizaOS Plugin

Local Development

Architecture

Deployment

Fly.io (recommended)

Docker

Environment Variables

Links

License

Score

Proud of your score? Add this badge to your README.

x402-api-server FAQ

How do I install x402-api-server?

Is x402-api-server an official MCP server?

Related MCP servers

Related guides

What `wrapFetchWithPayment` Does