arbitrum-transaction-preflight

Arbitrum 交易预检

为钱包、机器人和 AI Agent 提供付费交易模拟与风险报告。 在交易签名前，API 会检查交易能否成功模拟、估算 Gas、检测代币/NFT 授权、检查目标地址，并返回机器可读的风险评分。

生产 API：https://arbitrum-mpp-transaction-preflight-production.up.railway.app

产品与定价

• 网络：Arbitrum One（42161）
• 资产：原生 USDC（0xaf88d065e77c8cC2239327C5EDb3A432268e5831）
• 上线价格：每份报告 0.10 USDC（100000 个原始 USDC 单位）
• 主要支付渠道：基于 EIP-3009 的 MPP
• 可选分发渠道：基于 Coinbase CDP/Bazaar 的 x402
• Agent 接口：通过调用方钱包向 MPP 端点付款的 MCP stdio 服务

本服务绝不会要求提供用于签署交易的钱包。示例 MPP/MCP 客户端使用单独的低价值付款方密钥，仅用于授权 API 付款。

发现端点

托管服务提供免费的发现元数据：

• GET / — 产品、网络、价格和端点摘要
• GET /health — 健康检查
• GET /openapi.json — 支持 MPP 的 OpenAPI 3.1 发现文档
• GET /llms.txt — 面向 AI Agent 的简明说明
• GET /.well-known/agent.json — Agent/服务元数据

MPP 客户端调用：

POST /v1/preflight

启用 x402 后，x402 客户端调用：

POST /x402/v1/preflight

请求与报告

{
  "from": "0x0000000000000000000000000000000000000001",
  "to": "0x0000000000000000000000000000000000000002",
  "data": "0x",
  "valueEth": "0"
}

from 和 to 为必填项。data 默认值为 0x。原生资产金额可使用 valueEth 或 valueWei。成功完成付费请求后，响应包含：

• 调用模拟成功/回滚详情；
• Gas 估算值、Gas 价格和预估 ETH 成本；
• EOA/合约目标检查；
• ERC-20 approve 和 NFT setApprovalForAll 检测；
• 加权风险评分和警告；
• 区块号和检查时间戳。

自动模拟和启发式分析可以降低风险，但不能保证安全。

本地运行

要求：Node.js 22+ 和专用服务端钱包。在主网上，服务端钱包需要少量 Arbitrum One ETH 余额来支付 MPP 结算 Gas。

npm install
cp .env.example .env
npm run server

最低生产配置：

SERVER_PRIVATE_KEY=0x...
CHAIN_ID=42161
ARBITRUM_RPC=https://arb1.arbitrum.io/rpc
PRICE_RAW_USDC=100000
ENABLE_FREE_DEMO=false
SERVER_URL=https://arbitrum-mpp-transaction-preflight-production.up.railway.app

切勿提交 .env 或暴露 SERVER_PRIVATE_KEY。

MPP 客户端

随附的客户端会完成整个 402 -> authorization -> retry -> receipt 流程：

CLIENT_PRIVATE_KEY=0x...
TARGET_ADDRESS=0x...
SERVER_URL=https://arbitrum-mpp-transaction-preflight-production.up.railway.app
CHAIN_ID=42161

npm run client

付款方需要在 Arbitrum One 上持有原生 USDC。MPP 付款无需 ETH；商户会结算已签署的 EIP-3009 授权。

MCP 集成

MCP 服务提供 check_arbitrum_transaction 工具。它使用调用方的专用 CLIENT_PRIVATE_KEY 向托管的 MPP API 付款，因此每次工具调用都会产生 API 收入，而不是绕过付款。

npm run mcp

发布 npm 包后，MCP 宿主可以运行：

{
  "mcpServers": {
    "arbitrum-preflight": {
      "command": "npx",
      "args": ["-y", "arbitrum-mpp-transaction-preflight"],
      "env": {
        "CLIENT_PRIVATE_KEY": "0x...",
        "SERVER_URL": "https://arbitrum-mpp-transaction-preflight-production.up.railway.app",
        "CHAIN_ID": "42161"
      }
    }
  }
}

请使用专用的低价值付款方钱包。切勿重复使用持有大量资产的钱包密钥。

启用 x402 和 Bazaar

Arbitrum 上的生产 x402 结算使用 Coinbase 的 CDP 中介服务。创建 CDP 项目，并添加以下 Railway 变量：

ENABLE_X402=true
CDP_API_KEY_ID=...
CDP_API_KEY_SECRET=...

随后，服务端会通过 Bazaar 发现元数据提供 POST /x402/v1/preflight。MPP 仍可通过 POST /v1/preflight 使用；两个支付渠道共用相同的分析引擎和商户地址。

开发检查

npm run typecheck
npm run build
npm pack --dry-run

仅在本地开发时设置 ENABLE_FREE_DEMO=true，以免付款即可调用 POST /demo/preflight。切勿在生产环境中启用。

发布渠道

仓库中包含用于官方 MCP Registry 的 server.json 和 npm 元数据。发布顺序：

1. 将此版本部署到 Railway；
2. 将 arbitrum-mpp-transaction-preflight 发布到 npm；
3. 使用 mcp-publisher 发布 server.json；
4. 启用 CDP x402，以便纳入 Bazaar 索引；
5. 将线上 MPP 端点提交到 MPP 服务目录。

Arbitrum 官方 MPP 指南： https://docs.arbitrum.io/build-decentralized-apps/machine-payments-protocol