X402 API Server

x402 API服务器

使用HTTP 402支付的每次呼叫加密/DeFi数据API。\ 没有API密钥。没有订阅。AI代理根据请求在Base上支付USDC。

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

🌐 居住地址： https://x402-api.fly.dev\ 🤖 代理身份： #18763年在基地（ERC-8004）\ 📝 博客文章： 我建立了一个DeFi数据API，人工智能代理每次通话付费

______________________________________________________________________

这是什么？

这是一个DeFi/加密数据API服务器，其中 支付是HTTP协议本身的一部分.

每个端点都需要一笔小额美元支付，在0.001到0.008美元（几分之一）之间。当客户端点击受保护的端点时，服务器会以 HTTP 402 Payment Required 以及精确的付款指示。客户端付款，重试证明，并获取数据。

没有账户。没有OAuth。没有计费仪表板。只是： *“这要花0.003美元——在这里付款。”*

该模型专为 AI代理：需要调用API而无需人类伸手去拿信用卡的自主软件。代理人拿着钱包，支付所需的费用，然后继续前进。

堆栈：

• x402协议 --Coinbase基于HTTP 402的微支付标准
• 美元兑加元 基础 --L2主网，次级费用，即时终结
• ERC-8004 --人工智能代理的链上身份注册
• Express.js后端——简单、可审计、无框架魔法

______________________________________________________________________

端点

查询参数

______________________________________________________________________

x402的工作原理

这 x402协议 延长被遗忘已久的时光 HTTP 402 Payment Required 将状态码转换为机器可读的小额支付标准。

付款流程

步骤1-初始请求（无付款）

GET /api/price-feed HTTP/1.1
Host: x402-api.fly.dev

步骤2--服务器返回402

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"]
    }
  }]
}

步骤3——客户付款并重试

GET /api/price-feed HTTP/1.1
Host: x402-api.fly.dev
X-Payment: 

步骤4--服务器验证并响应

HTTP/1.1 200 OK
X-Payment-Response: {"success":true,"txHash":"0x..."}
Content-Type: application/json

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

付款验证

在当前回购中，生产就绪支付证明路径为：

1. 交易哈希 --确认提交的基本交易包含向收款地址转账的USDC。

回购还支持 EIP-3009 transferWithAuthorization 当您配置其中一项时结算：

1. 直接解决 通过 X402_SETTLEMENT_PRIVATE_KEY --服务器提交 transferWithAuthorization 上链并支付汽油。
2. 自定义协调人结算 通过 X402_FACILITATOR_URL --服务器将签名的授权转发给您的主持人。

如果不配置其中任何一个，部署将保留在 txHash 仅限付款证明路径。

收款钱包： 0x60264c480b67adb557efEd22Cf0e7ceA792DefB7\ 网络： 基础主网（链ID 8453）\ 资产： USDC(0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

______________________________________________________________________

与x402一起使用

x402获取 是Coinbase的官方客户端库，自动处理支付流程。把它作为一个 fetch 替换。

安装

npm install x402-fetch viem

基本用法

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);

什么 wrapFetchWithPayment 是否

1. 发出初始请求
2. 如果402→ 解析付款要求
3. 签署付款授权（EIP-3009 transferWithAuthorization)
4. 使用以下命令重试请求 X-Payment 头球
5. 返回成功响应

注意：这是标准的x402客户端流。当前的服务器仓库还支持一种更简单的证明格式，其中客户端首先在链上付款，然后发送Base64 JSON X-Payment 标题如下：

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

您的钱包需要Base主网上的USDC。 您可以使用以下工具将USDC从以太坊桥接到Base 基础桥 或者直接在Coinbase上购买。

______________________________________________________________________

ERC-8004标识

此API通过注册为Base上的AI代理 ERC-8004 --以太坊链上代理身份标准。

代理ID: #18763\ 注册合同： 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432\ 网络： 基础主网

注册包括：

• 代理名称和描述
• 服务端点（web+x402）
• x402能力标志
• 基于声誉的信任信号

这使得发现服务、人工智能市场和其他代理可以在链上找到并验证此API-无需集中式注册。

查看注册数据： agent-registration.json

______________________________________________________________________

集成

MCP服务器（Claude Desktop/Claude API）

MCP（模型上下文协议）服务器现在位于其自己的独立仓库中：

• github： fernsugi/x402 api mcp服务器
• npm： @x402-api/mcp-server

快速设置：

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

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

添加到克劳德桌面 (claude_desktop_config.json):

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

→ 请参阅独立的MCP仓库以获取完整文档： x402 api mcp服务器自述文件

Elizaos插件

这 elizaos-plugin/ 该目录包含一个ElizaOS插件，该插件为自主代理提供了对所有8个端点的自然语言访问。

安装：

npm install @x402-api/elizaos-plugin

在您的ElizaOS代理商处注册：

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

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

该插件增加了8个操作： 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 查看完整文档。

______________________________________________________________________

本地开发

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

处于开发模式(NODE_ENV=development)，任何非空 X-PAYMENT 标题被接受——本地测试不需要实际付款。

# 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"

______________________________________________________________________

建筑

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

______________________________________________________________________

部署

Fly.io（推荐）

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

码头工人

docker compose up -d

环境变量

______________________________________________________________________

链接

• 🌐 着陆页
• 📖 x402协议
• ⛓️ 基础链
• 🔎 BaseScan上的代理#18763
• 📝 ERC-8004规范
• 🤖 MCP 服务器
• 🤖 Elizaos插件

______________________________________________________________________

许可证

麻省理工学院