x402 Micro Tollgate

x402-micro-tollgate

为无法持有银行卡的 AI Agent 办理 Visa。

面向 Agent 流量的秒级结算桥梁——基于 Web3 的收费站，可结算 USDC 小额支付，收取 0.1% 费用。

为千万级无支付能力的 AI Agent 提供秒级过桥清算，抽成 0.1% 的 Web3 版 Visa 收费站

安全保障由 Coinbase CDP 提供。 我们不会接触你的密钥，也不会使用自定义密码学结算支付——EIP-3009 授权 nonce 在 CDP facilitator 处只能使用一次（CDP 是链上唯一性的事实来源）。网关会强化买卖双方信任链路中的四个环节：支付凭证重放／竞态、URL 获取中的 SSRF、**上游绕过（共享密钥信任请求头）**以及 Base 网络拥堵／结算延迟（待处理时使用相同凭证重试——绝不能仅因 HTTP 超时就判定“支付失败”）。

它是什么

一个可自托管的轻量收费站，部署在你的 API 或 MCP 工具前方。当 Agent 调用付费路由时，会收到作为价格标签的 HTTP 402（而非直接拒绝）。它支付少量 USDC（或配置的 USDT），你提供服务。默认通过 Coinbase CDP 在 Base + USDC 上清算；可通过环境变量配置多网络接受选项（见下方矩阵）。用户仍可访问免费路径；Agent 则在收费站完成支付。

自托管免费（MIT）。代码仓库：github.com/kevin2003050666-coder/x402-micro-tollgate · 问题咨询：[email protected]

非 Coinbase 官方产品。不是完整的 Agent 市场。不是计费 SaaS。是一座利落的 Visa 式收费站。不托管法币。

项目缘起：MANIFESTO.md——痛点、工程、链上证明、MIT。

网络 × 资产矩阵

默认部署配置：仅支持 Base USDC（开发环境：Base Sepolia）。通过 NETWORKS + ASSETS 或 ACCEPTS_JSON / X402_* 别名启用多网络。配置多个接受选项时，浏览器 HTML 402 页面会显示链 + 资产选择器。

Network	CAIP-2	USDC	USDT	Status	Facilitator / notes
Base	eip155:8453	原生 Circle	桥接	上线	CDP exact。FeeSplitterFactory 已上线 (deployments/base.json)
Base Sepolia	eip155:84532	测试 USDC	—	上线	CDP 测试网
Optimism	eip155:10	原生	桥接	配置就绪	已接入地址；当前 CDP 矩阵中不包含
Arbitrum One	eip155:42161	原生	桥接	上线	CDP exact；工厂合约存根
Polygon PoS	eip155:137	原生（非 USDC.e）	PoS USDT	上线	CDP exact；工厂合约存根
BNB Smart Chain	eip155:56	锚定资产，18 位小数	锚定资产，18 位小数	配置就绪	不在 CDP 列表中
Ethereum	eip155:1	原生	Tether	配置就绪	取决于 facilitator
Avalanche C-Chain	eip155:43114	原生	USDT	配置就绪	包含在 @x402/evm 默认值中
Celo / Sei	eip155:42220 / 1329	USDC	—	配置就绪	目录附加项
Solana	solana:5eykt…	SPL USDC	SPL USDT	实验性	CDP 列出 Solana；网关存根 + 可选 SVM 付费墙（SOLANA_PAY_TO）
TRON	tron:mainnet	—	TRC-20	计划中	依赖项中没有对应方案——绝不会出现在 accepts[] 中

EVM 上的 USDT 通常使用 extra.assetTransferMethod: "permit2"（而非 EIP-3009）。FeeSplitter 生产路径仍为 Base + USDC；其他链在 contracts/deployments/ 下仅有配置存根。

浏览器钱包

Wallet	Role
Coinbase Smart Wallet (Passkey)	主要行动号召
MetaMask	通过 wagmi 注入式目标
注入式	其他浏览器钱包
WalletConnect	设置 WALLETCONNECT_PROJECT_ID 时可用
Solana 付费墙	实验性，仅在启用 Solana 接受选项／PAYWALL_SVM 时可用
TronLink	不提供（TRON 仅计划支持）

---

适用对象

• API 销售方：希望让 Agent 按调用付费，而无需构建计费控制台或销售月度席位
• 工具构建者：将付费 MCP 端点部署到 Cursor / Claude
• 运营者：希望采用类似 Visa 的费率经济模式（0.1%），而不是支付托管账单

资金如何流转

1. 标价 — 未付费流量会收到 HTTP 402，告知应付金额（促成转化，而非拒绝请求）
2. 付款 — Agent 通过 Coinbase CDP 在几秒内完成 USDC 小额支付
3. 解锁 — 收费关卡代理请求到你的上游服务；你保留约 99.9%，协议抽取 0.1%

协议不收月费。收费关卡就是变现方式——类似银行卡网络的交换费。

---

1 分钟快速入门

需要 Node.js 22+。

git clone https://github.com/kevin2003050666-coder/x402-micro-tollgate
cd x402-micro-tollgate && cp .env.example .env
# set CDP_API_KEY_ID, CDP_API_KEY_SECRET, X402_PAY_TO (optional: PUBLIC_BASE_URL, UPSTREAM_URL)
npm i && npm start
# curl http://127.0.0.1:8402/health   → 200
# curl http://127.0.0.1:8402/x402/discover → 200 (free agent yellow pages)
# curl http://127.0.0.1:8402/v1/quote → 402
# curl "http://127.0.0.1:8402/v1/fetch-md?url=https://example.com" → 402 (paid HTML→Markdown demo)

npx 单行命令（无需克隆）：

npx [email protected]
npx [email protected] --seller 0xYourReceivingAddress --stdio

--seller / -s 会在启动前设置 X402_PAY_TO（环境变量仍然可用）。未指定 --stdio 时，默认使用 HTTP，并在 8402 端口提供 /mcp。

Agent / 爬虫文档：llms.txt（也可通过 GET /llms.txt 和 GET /.well-known/llms.txt 访问） · OpenAPI 3.1：docs/openapi.yaml · well-known：GET /.well-known/x402.json、GET /.well-known/agent-card.json

替代单行命令：docker compose up --build

未配置 CDP 密钥时，进程将以演示模式运行（返回符合协议格式的 402 / MCP PaymentRequired，不进行链上结算）。

Cursor mcp.json：

{
  "mcpServers": {
    "x402-micro-tollgate": {
      "url": "http://127.0.0.1:8402/mcp"
    }
  }
}

Stdio：

{
  "mcpServers": {
    "x402-micro-tollgate": {
      "command": "npx",
      "args": [
        "[email protected]",
        "--seller",
        "0xYourReceivingAddress",
        "--stdio"
      ],
      "env": {
        "CDP_API_KEY_ID": "...",
        "CDP_API_KEY_SECRET": "...",
        "PUBLIC_BASE_URL": "https://your.public.host"
      }
    }
  }
}

（即使省略 --seller，在 env 中设置 X402_PAY_TO 仍然有效。）

库接入（无需许可的销售方）

import express from "express";
import { x402Tollgate } from "x402-micro-tollgate";

const app = express();
app.use("/v1", await x402Tollgate({ seller: process.env.SELLER! }));

或者在 .env 中设置 SELLER / X402_SELLER，然后运行 npm start。有关 $10 阈值、工厂地址和费用释放详情，请参阅环境变量。

买方 / Agent 客户端

轻量 TypeScript 辅助工具，封装官方 @x402/fetch + @x402/evm ExactEvmScheme。收到 HTTP 402 时，它会解析 PAYMENT-REQUIRED、检查预算、签署一次 EIP-3009，并使用 PAYMENT-SIGNATURE 重试一次（绝不循环）。

npm i [email protected]

import { createX402Fetch } from "x402-micro-tollgate/client";
const fetch402 = createX402Fetch({ privateKey: process.env.BUYER_KEY as `0x${string}` });
const res = await fetch402("https://x402-micro-tollgate.onrender.com/v1/quote");

默认值：maxSingleSpendUsdc = 0.05、maxTotalSpendUsdc = 1.00（超出时会抛出清晰的 Error）。断路器（签名之前）：每滚动 60 秒最多 10 次付费 402 / 0.05 USDC，并支持指纹死循环停机保护（maxPaidRequestsPerMinute、maxSpendUsdcPerMinute、enableFingerprintBreaker）。**热钱包警告：**签名密钥中只保留约 $5–$10 USDC——将其视为 Agent 消费水龙头，而非资金库。

人类委托的 Agent 信用额度（CLI）

轻量概念验证：人类设置 B_max → Agent 针对付费 URL 循环调用 createX402Fetch（自动收到 402 → 付款一次 → 重试）。Chrome / Telegram / Session Key / Passkey UI 暂不实现。

# SAFETY: fund BUYER_PRIVATE_KEY with ≤ $5–$10 USDC only. Never commit keys.
export BUYER_PRIVATE_KEY=0xYourHotWalletKey
# optional: TARGET_URL MAX_SINGLE_USDC MAX_TOTAL_USDC ROUNDS
npm run poc:buyer-agent
# or: npx tsx scripts/buyer-agent-poc.ts

环境变量	默认值	说明
BUYER_PRIVATE_KEY	(必填)	用于签署 EIP-3009 的 0x… EOA
TARGET_URL	https://x402-micro-tollgate.onrender.com/v1/quote	要访问的付费路由
MAX_SINGLE_USDC	0.05	单次调用上限（maxSingleSpendUsdc）
MAX_TOTAL_USDC	1.00	会话上限 / 人类设置的 B_max
ROUNDS	3	达到 N 次调用或预算耗尽时停止

脚本导入本地客户端（../src/client），因此仓库 CI 无需进行实时链上支付。要使用已发布的软件包进行实时演示，请将导入路径改为 x402-micro-tollgate/client（API 与 0.3.2+ 相同）。每轮会在 stdout 输出 status、autoPaid 和 sessionSpendUsdc；安全提示横幅会输出到 stderr。

---

部署

使用 render.yaml：Node 22、npm start、健康检查路径 /health，环境变量名称见 .env.example。如需进行实时结算，请在控制面板中设置 CDP_API_KEY_ID、CDP_API_KEY_SECRET 和 X402_PAY_TO；将 PUBLIC_BASE_URL 设置为你的 https://….onrender.com 源站，以供 Bazaar 使用。

运维更新：重新部署 discover + well-known（强制触发 Render GitHub 自动部署，使生产环境启用 GET /x402/discover、GET /.well-known/x402.json、GET /.well-known/agent-card.json 和 MCP fetch_md）。如果此更改合并到 main 后几分钟内未触发自动部署，请前往 Render 控制面板 → Manual Deploy → Deploy latest commit。

**自托管生产环境：**Docker — docker compose up --build（参见 Dockerfile / docker-compose.yml）。

---

环境

变量	默认值	说明
PORT	8402	HTTP 监听端口
UPSTREAM_URL	(unset → mock)	你的 API 源站
UPSTREAM_SHARED_SECRET / X402_UPSTREAM_SECRET	—	可选。结算后，tollgate 会注入 X-Tollgate-Secret + X-Tollgate-Paid（HMAC）。上游必须要求这些标头并拒绝公开的直接请求（非 mTLS）
X402_PAY_TO	—	EVM 收款地址（实时模式 SDK 初始化）
SELLER / X402_SELLER	—	无需许可的卖家 EOA（经过 EIP-55 验证；无效时 → 启动失败）
FACTORY_ADDRESS	—	操作员设置的 FeeSplitterFactory，用于金额 ≥ 阈值时进行 CREATE2 预测（Base 实时地址见 contracts/deployments/base.json；不要硬编码密钥）
FEE_FREE_BELOW_USDC / X402_FEE_FREE_BELOW_USDC	10000000	USDC 最小单位（6 位小数）。< $10 → payTo=seller；≥ $10 → FeeSplitter
CDP_API_KEY_ID / CDP_API_KEY_SECRET	—	CDP facilitator（以及 Onramp 会话令牌）
CDP_CLIENT_API_KEY	—	用于浏览器 Smart Wallet 付费墙的公开 CDP 客户端密钥（可安全用于前端）。别名：CDP_CLIENT_KEY
X402_FACILITATOR_URL / CDP_FACILITATOR_URL	CDP 默认值	MCP 的可选备用 facilitator 基础 URL（createCdpFacilitatorClient({ baseUrl })）。仅支持单一供应商；尚不支持多 facilitator 路由
PRICE	$0.001	网络默认 USDC/USDT 价格标签
NETWORK / X402_NETWORK	eip155:84532 / 8453	主 CAIP-2（别名：base、optimism 等）
NETWORKS / X402_NETWORKS	(仅主网络)	用于多网络接受支付的逗号分隔/JSON 网络列表
ASSETS / X402_ASSETS	USDC	与 NETWORKS 交叉组合 → 接受的资产（USDC、USDT）
ACCEPTS_JSON / X402_ACCEPTS_JSON	—	显式接受支付数组（覆盖 NETWORKS×ASSETS）
FACTORY_ADDRESSES	—	caip2 → FeeSplitterFactory 的 JSON 映射（Base 为实时地址；其他网络可选）
SOLANA_PAY_TO	—	用于实验性 Solana 接受支付的 Base58 payTo
PAYWALL_SVM	false	强制使用 @x402/paywall SVM UI（接受支付中包含 Solana 时也会自动启用）
WALLETCONNECT_PROJECT_ID	—	在浏览器付费墙中启用 WalletConnect
X402_MIN_PRICE_USDC	—	可选的静态最低接受金额（USDC 最小单位）。有效价格 = max(PRICE, 此值, Gas 下限)
X402_DYNAMIC_MIN_ENABLED	false	设为 true 时，如果 Gas 成本会吞噬过多支付金额，Base 基础费用预言机可能会提高最低接受金额 / feeFreeBelow
X402_GAS_COST_MAX_FRACTION	0.5	预计 Gas 美元成本 > 支付金额的此比例时提高金额
X402_GAS_ORACLE_TTL_MS	30000	baseFee 缓存 TTL（限制在 15–60 秒）
X402_GAS_RPC_URL / BASE_RPC_URL	Base 公共 RPC	用于 eth_getBlockByNumber baseFee 的 JSON-RPC
X402_GAS_USED_ESTIMATE	100000	用于估算结算成本的粗略 L2 Gas 单位数
X402_ETH_USD	4000	保守的 ETH/USD 下限（无需实时汇率）
X402_ENVIRONMENT	development	或 production
GATED_PREFIX	/v1	需要支付的 HTTP 路径
PUBLIC_BASE_URL	http://127.0.0.1:$PORT	用于 Bazaar 资源 URL 的公开 https:// 源站
CONTACT_EMAIL	[email protected]	落地页联系邮箱 mailto（不是 SaaS 行动号召）
FEE_BPS	10	文档所述的操作员费用（0.1%）。实时结算仍会将 100% 支付给 payTo，直到调用 release()
FEE_COLLECTOR	0xa922…7e30E	FeeSplitter.release() 后收取 0.1% 份额的固定操作员钱包
MERCHANTS_JSON	—	可选的托管式多租户注册表（设置 SELLER 时不需要）
MERCHANTS_FILE	merchants.json	文件路径；未设置卖家时回退到 merchants.example.json / 内置演示数据
DEFAULT_MERCHANT	demo	省略 ?merchant= / x-merchant-id 时使用 — Agent 应始终发送 merchant id
REQUIRE_MERCHANT	false	设为 true 时，受限路径会对缺少 merchant id 的请求返回 400 {error:"merchant_required"}（不回退到演示数据）
PAYMENT_DEDUPE_TTL_MS	600000	内存中的支付证明幂等窗口（10 分钟）。CDP facilitator nonce 仍是事实来源
PAYMENT_DEDUPE_MAX_ENTRIES	10000	网关 PaymentDedupeStore LRU 中的最大键数（无 Redis；接口已为 Redis 做好准备）
X402_VERIFY_TIMEOUT_MS	15000	文档所述的验证阶段预算（本地 / facilitator 验证）
X402_SETTLE_TIMEOUT_MS	180000	等待 facilitator/链上结算后再返回 202 payment_pending（默认 3 分钟 — Base 网络拥堵）
KEEPER_ENABLED	false	可选的 FeeSplitter release() keeper — 默认绝不启用
KEEPER_DRY_RUN	(见说明)	true 时记录 keeper_would_release，但不发送交易
KEEPER_PRIVATE_KEY	—	仅用于实时 release() 的 EVM 密钥（切勿提交）
KEEPER_RPC_URL	Base 公共 RPC	用于余额查询和 release 的 JSON-RPC 端点
KEEPER_INTERVAL_MS	3600000	轮询间隔（1 小时）
KEEPER_MIN_USDC	1000000	调用 release() 前所需的最低 USDC 余额（最小单位）— 默认 $1

无需许可的卖家 + $10 门槛（0.3.0）

0.3.0：设置 SELLER（或使用 x402Tollgate({ seller })）和 FACTORY_ADDRESS，以启用 ≥ $10 的 CREATE2 路由。无需 MERCHANTS_JSON。

金额（USDC 最小单位，6 位小数）	accepts[].payTo
< 10_000_000（$10）	卖家 EOA — 协议费为 0
≥ 10_000_000（$10）	为该卖家预测的 CREATE2 FeeSplitter

x402 exact + EIP-3009 只会将资金记入 payTo — 不会执行 FeeSplitter / 工厂代码，也不会在同一笔交易中分账。对于 ≥ $10：将 FACTORY_ADDRESS 设为由运营方部署的工厂（Base 参考：contracts/deployments/base.json），在首次进行此类结算前调用 getOrCreate(seller)，之后再调用 release()（99.9% / 0.1%）。地址拼写错误会导致资金发送到错误地址 — 网关会在启动时校验 SELLER 的校验和。不要在源代码中硬编码私钥或运营方机密。

商户注册表（可选的托管式多租户）

运营方的 FEE_COLLECTOR 固定为：0xa922F38041B5ee227c96A547F106F1330447e30E。每个商户都有自己的 FeeSplitter（seller = 商户钱包，feeCollector = 运营方，feeBps = 10）。注册表将 merchantId 映射到拆分器地址（payTo）以及用于显示的卖家。设置 SELLER 后，注册表为可选项；如果提供 MERCHANTS_JSON，?merchant= 仍然有效。

注册商户：

1. 部署 FeeSplitter，其中 seller = 商户钱包，feeCollector = 0xa922F38041B5ee227c96A547F106F1330447e30E，feeBps = 10，asset = 链的原生 USDC。
2. 在 MERCHANTS_JSON（或 merchants.json / 从 merchants.example.json 复制）中添加一条记录：

   {
     "acme": {
       "seller": "0xMerchantWallet…",
       "payTo": "0xDeployedFeeSplitter…",
       "label": "Acme API"
     }
   }
   

3. 使用 ?merchant=acme 或请求头 x-merchant-id: acme（不区分大小写）调用受门控的 API。**Agent 应始终发送商户 ID。**如果省略，网关会回退到 DEFAULT_MERCHANT（demo）— 这意味着流量（和 USDC）可能会悄无声息地进入 demo FeeSplitter。设置 REQUIRE_MERCHANT=true，即可在缺少商户信息时返回 400 { "error": "merchant_required" }。受门控路径上的未知商户 → 400 { "error": "unknown_merchant" }。
4. 免费目录：GET /merchants（也支持 /v1/merchants）。
5. Agent 黄页：GET /x402/discover（别名 GET /discover）— 根据同一注册表 / SELLER / demo 生成稳定的 JSON 目录。仍支持 JSON 配置；此版本没有链上 Registry.sol 的 $5 质押机制。

**注意：**Base demo 拆分器的 seller = feeCollector = 运营方 — 对 demo 来说没问题。真实商户需要使用自己的钱包作为 seller，并部署自己的拆分器。

CDP createX402Server 在 SDK 初始化时使用单一全局 payTo（X402_PAY_TO 或默认商户拆分器）。按请求进行的商户路由会将 PAYMENT-REQUIRED accepts[].payTo 重写为解析出的 FeeSplitter（与 https resource.url 重写模式相同）。

如果 X402_PAY_TO 仍为 EOA 且你只有一个商户，行为会保持简单。多商户生产环境应将注册表中的每个 payTo 指向已部署的拆分器 — x402/exact 会通过 EIP-3009 将资金记入该拆分器；之后调用 release()（手动调用或通过可选的 keeper），以发送 99.9% / 0.1%。Base / Arbitrum / Polygon 上使用同一合约 — 参见多链 FeeSplitter 矩阵。这是先接收、之后调用 release()，并非在同一笔交易中原子分账，也不是 OpenZeppelin PaymentSplitter。

发现（实时）+ 流动性路线图（规划中）

立即上线 — 仅发现功能。 免费路由 GET /x402/discover（别名 /discover）基于现有来源（MERCHANTS_JSON / merchants 文件 / SELLER / 内置演示）和 PUBLIC_BASE_URL，返回供 Agent 读取的黄页信息。无需 402。示例结构：

{
  "version": 1,
  "network": "eip155:8453",
  "updatedAt": "2026-09-03T00:00:00.000Z",
  "source": "merchants",
  "services": [{
    "id": "demo",
    "label": "demo (operator is also seller)",
    "endpoint": "https://your-host/v1/quote?merchant=demo",
    "mcp": "https://your-host/mcp",
    "capabilities": ["quote", "proxy", "fetch-md"],
    "price": "$0.001",
    "asset": "USDC",
    "payTo": "0x…",
    "seller": "0x…",
    "status": "demo"
  }]
}

status 如实反映健康状态：仅在配置了 CDP facilitator 凭据和 payTo 时为 live；否则为 demo（如果 accepts 非实时，则为 config）。这不是链上 Agent Registry。

规划中（仅有文档说明 — 请勿视为已上线）：

方向	当前为何不上线
闪电流动性池（跨链 0 确认垫付）	资金密集：独立创始人无法持有多链 USDC 浮动资金。0 确认垫付 = 信用风险。热钱包余额不足时需要断路器。如果 Superchain / AggLayer 实现亚秒级原生互操作性，跨链摩擦 (S_{cross}) → 0，该方向可能会缩减。
反向赏金（付费让 Agent 调用）	如果卖家补贴调用，就会遭遇 Sybil 攻击导致资金耗尽。在任何 claimBounty 之前，必须设置速率限制、按 Agent 身份识别以及 IP+指纹门槛。当前约 $20 的 Discord/X 赏金仍为人工运营者付款，不是链上领取。

完整说明：docs/ROADMAP-LIQUIDITY.md。本次发布不包含 FeeSplitter 上的 depositBounty / claimBounty，也不包含虚假的“实时”跨链清算声明。

发现层已上线（GET /x402/discover）；闪电流动性池与反向赏金仅为规划，见路线图。

Gas 与微支付下限（可选）

微支付（$0.001–$0.01）假设 Base 费用较低。当 L2 gas 飙升时，预估结算成本可能吞噬小额支付的大部分金额。启用 X402_DYNAMIC_MIN_ENABLED=true 可选择加入：缓存的 Base baseFee 预言机（TTL 15–60s，不会频繁请求 RPC）会估算 gas 美元成本（gasUsedEstimate * baseFee * X402_ETH_USD）；如果该成本超过支付金额的 X402_GAS_COST_MAX_FRACTION（默认 50%），就会提高显示和强制执行的最低接受金额，并可能提高 feeFreeBelow，避免在金额较大之前使用 FeeSplitter+release()。默认关闭，因此在正常情况下，演示用的 $0.001 仍可使用。运营者也可以设置静态的 X402_MIN_PRICE_USDC。当前生效的最低金额可在 GET /health → gasFloor 中查看。

安全（网关加固）

买家和卖家应了解以下四项防护：

1. 支付签名重放 / 竞态 — 幂等键 = SHA-256(PAYMENT-SIGNATURE)。进程内互斥锁 + PaymentDedupeStore（目前为内存实现；接口兼容 Redis）会在请求上游之前执行“仅当不存在时设置”。并发请求中的失败方会收到 409 { "error": "payment_already_used" }。只有在结算成功之后才会持久标记；验证失败时会释放待处理预留，因此不会阻断诚实的重试。
2. /v1/fetch-md 上的 SSRF — 仅允许 http / https；DNS 解析会拒绝私有地址、bogon 地址、链路本地地址和元数据地址；抓取前会重新检查 DNS（防止 DNS 重绑定）；禁用重定向。
3. 绕过上游 — 可选的 UPSTREAM_SHARED_SECRET：付款后，代理会注入 X-Tollgate-Secret / X-Tollgate-Paid / X-Tollgate-Timestamp。你的上游必须要求这些标头（见下方代码片段）。这是共享密钥 MVP，不是 mTLS。
4. Base 拥塞 / 结算延迟 — X402_SETTLE_TIMEOUT_MS（默认 3 分钟）与较短的验证时限相互独立。如果等待者超时后结算仍在进行中 → 202 { "error": "payment_pending", "retry_with_same_proof": true }。不要创建新支付，也不要仅仅因为 HTTP 超时就认定买家失败 — 使用同一份凭证重试；网关会继续处理，不会重复结算。

默认情况下，CDP facilitator 是单一供应商的结算依赖；关于 X402_FACILITATOR_URL（可用时使用其他 facilitator — 目前尚不支持多 facilitator 路由），请参阅 SECURITY.md。

支付凭证幂等性 + 结算待处理状态

CDP x402 exact + EIP-3009 授权在 facilitator 处只能使用一次（nonce）。网关还会将每个凭证指纹跟踪为 pending → settled → consumed：

存储状态	客户端看到的内容
pending（结算进行中 / 结算等待超时后）	202 payment_pending + retry_with_same_proof: true
settled（已付款；尚未传递上游）	跳过重新结算；代理一次；标记为 consumed
consumed	409 payment_already_used

默认仅在进程内保存（重启后清除）。链上 nonce 的唯一性仍由 facilitator 权威保障。

上游信任标头（Express 示例）

import { createHmac, timingSafeEqual } from "node:crypto";
import type { RequestHandler } from "express";

const SECRET = process.env.UPSTREAM_SHARED_SECRET!;

export const requireTollgate: RequestHandler = (req, res, next) => {
  const secret = req.header("x-tollgate-secret") ?? "";
  const paid = req.header("x-tollgate-paid") ?? "";
  const ts = req.header("x-tollgate-timestamp") ?? "";
  const expected = createHmac("sha256", SECRET)
    .update(`${ts}.${req.method.toUpperCase()}.${req.path}`, "utf8")
    .digest("hex");
  const okSecret =
    secret.length === SECRET.length &&
    timingSafeEqual(Buffer.from(secret), Buffer.from(SECRET));
  const okPaid =
    paid.length === expected.length &&
    timingSafeEqual(Buffer.from(paid), Buffer.from(expected));
  if (!okSecret || !okPaid) {
    res.status(401).json({ error: "tollgate_required" });
    return;
  }
  next();
};

// app.use(requireTollgate); // reject public direct hits

也可以在上游进程中从 x402-micro-tollgate 导入 verifyUpstreamTrustHeaders。

可选 FeeSplitter 释放 keeper

脚手架位于 src/keeper.ts。默认关闭（未设置 KEEPER_ENABLED 或设为 false）。启用后，每隔 KEEPER_INTERVAL_MS（默认 1h）检查注册表中 payTo FeeSplitter 地址的 USDC 余额，并在余额 ≥ KEEPER_MIN_USDC（默认 $1）时调用 release()。

**警告：**小额支付中，release() 的 Gas 费用可能超过 0.1% 的运营方手续费，因此需要设置最低余额门槛。不要在 Render 上默认开启此功能。建议先使用 KEEPER_DRY_RUN=true（记录 keeper_would_release），再使用真实的 KEEPER_PRIVATE_KEY。切勿提交密钥。

---

Bazaar 发现（Agent 查找卖家）

Bazaar 是 x402 发现目录。

• HTTP：createX402Server 会自动注入 Bazaar；我们通过覆盖设置 discoverable: true、描述和输入/输出架构（GET /v1/quote + 受保护前缀代理）。
• MCP：x402ResourceServer 不会自动声明 Bazaar——我们会注册 bazaarResourceServerExtension，并在 get_quote / proxy_request / fetch_md 上传入 declareDiscoveryExtension({ toolName, inputSchema, … })。资源 URL 为 PUBLIC_BASE_URL/mcp（真实的 http(s) URL，而非显示名称）。
• Origin well-known：GET /.well-known/x402.json（别名 /.well-known/x402）镜像 discover，并列出可用的付费 HTTP/MCP 资源，供不依赖 facilitator 的爬虫使用。

要出现在 Bazaar 中：

1. 将 PUBLIC_BASE_URL 设为公开的 https origin（localhost 列表对真实爬虫不起作用）。
2. 使用有效的 CDP 凭据和 X402_PAY_TO 运行。
3. 通过 CDP facilitator 成功结算一次（受保护路由上的空请求体探测会返回 402，而非 400）。

上线提示：首次成功结算后，在 Discord #x402 分享你的 /mcp 或 /v1/quote URL。

---

在浏览器中支付（Smart Wallet）

当浏览器访问受保护路由时（Accept: text/html + Mozilla UA），网关会返回精简的 HTML 支付墙，而非 JSON。Agent / MCP / curl 仍会收到 JSON 402 响应体。

你将获得

1. 通过官方 @x402/paywall EVM UI 连接 / 创建 Coinbase Smart Wallet（Coinbase Wallet connector — Passkey Smart Wallet，无需 MetaMask）。
2. 在 Base（或开发环境中的 Base Sepolia）上签署 x402 exact EIP-3009 支付，并使用 PAYMENT-SIGNATURE 重试。
3. 获取 USDC（可选）：设置服务器 CDP 密钥后，支付墙会显示一个获取 USDC按钮，该按钮会调用 POST /x402/session-token 并打开 Coinbase Onramp。只有当 Onramp 支持你的域名时，才会显示 Apple Pay / 银行卡选项——本仓库不会在 Onramp 之外伪造 Apple Pay，也不会在没有 Portal 生产环境访问权限的情况下宣称能保证“10 秒 Apple Pay”。

设置（买家体验）

# .env — server secrets stay on the host
CDP_API_KEY_ID=…
CDP_API_KEY_SECRET=…
X402_PAY_TO=0x…          # or SELLER=0x…

# Public client key only (browser-safe)
CDP_CLIENT_API_KEY=…     # from portal.cdp.coinbase.com

# Optional but recommended for live demo / Bazaar
PUBLIC_BASE_URL=https://your.host
X402_ENVIRONMENT=development   # Base Sepolia (eip155:84532)
# X402_ENVIRONMENT=production  # Base mainnet (eip155:8453)

部件	作用
CDP_CLIENT_API_KEY	注入付费墙 HTML，作为 window.x402.cdpClientKey
CDP_API_KEY_ID + CDP_API_KEY_SECRET	用于 Facilitator 结算以及POST /x402/session-token（Onramp JWT）
POST /x402/session-token	免费路径；请求体 { "addresses": [{ "address": "0x…", "blockchains": ["base"] }], "assets": ["USDC"] } → { token }

说明 / 生产环境须知

• **MVP 网络：**Base Sepolia（development）和 Base 主网（production / NETWORK=eip155:8453）。
• **Onramp 生产环境：**在 CDP Portal 中启用 Onramp，将你的域名加入允许列表，并完成 Coinbase 要求的任何 Apple Pay 域名验证。在此之前，Smart Wallet 仍可完成支付、签名和重试；Get USDC 可能报错或不显示银行卡支付选项。
• **CSP：**付费墙包含内联脚本（与上游 @x402/paywall 相同）。对于 402 HTML 响应，最好不要在没有 nonce 的情况下设置严格的 script-src。
• **安全性：**钱包私钥不会接触前端；仅嵌入公开客户端密钥。会话令牌由服务端签发。

试试看：配置上述密钥后，在 Chrome 中打开 https://your-host/v1/quote。

---

功能

Agents / clients
   ├─ HTTP  /v1/*          → x402 402 JSON (agents) or Smart Wallet HTML paywall (browsers)
   ├─ GET   /v1/fetch-md   → paid HTML→Markdown demo (same x402 gate)
   ├─ GET   /x402/discover → free agent yellow pages (alias /discover; from merchants JSON)
   ├─ GET   /.well-known/x402.json → free Bazaar-friendly origin manifest (alias /.well-known/x402)
   ├─ GET   /.well-known/agent-card.json → free agent card (alias /.well-known/agent.json)
   ├─ GET   /llms.txt      → free AI-crawler summary (alias /.well-known/llms.txt)
   ├─ GET   /openapi.yaml  → free OpenAPI 3.1 (alias /docs/openapi.yaml)
   ├─ POST  /x402/session-token → free Onramp session token (when CDP server keys set)
   ├─ GET   /merchants     → free merchant registry (id, label, seller, payTo)
   ├─ GET   /health        → free (+ paywall config flags)
   ├─ GET   /              → developer landing (EN / 中文)
   └─ MCP   /mcp           → server_info (free), get_quote + proxy_request + fetch_md (paid + bazaar)

接口	技术栈
HTTP	createX402Server + paymentMiddlewareFromHTTPServer + @x402/paywall（浏览器）
MCP	x402ResourceServer + createCdpFacilitatorClient + createPaymentWrapper + Bazaar 扩展

CLI：npx [email protected] | --seller 0x… / -s | --stdio | --port N

Agent SEO：llms.txt · docs/openapi.yaml

---

发布

包标识（必须保持一致）：

• package.json 中的 mcpName = io.github.kevin2003050666-coder/x402-micro-tollgate
• server.json 中的 name = 相同字符串

流程（需要在拥有相应令牌的机器上执行，不能在此 VM 上执行）：

1. 发布到公开 GitHub 镜像 kevin2003050666-coder/x402-micro-tollgate
2. 执行 npm publish（或打上标签 v* → .github/workflows/publish-mcp.yml）
3. 执行 mcp-publisher publish（OIDC）→ 官方 MCP Registry
4. PulseMCP 会自动从官方注册表导入——不要直接提交到 PulseMCP

发布远程服务前，将 server.json 中的 remotes[0].url 更新为真实的公开 /mcp 地址。

---

测试

npm test

无需有效的 CDP 凭据。

---

许可证

MIT · 参见 CONTRIBUTING.md · SECURITY.md