Hive Agent Quota

hive-mcp-agent-quota

A2A 网络的 Agent 配额计量器。每次调用 quota_check 都会从 Agent 的 DID 扣除一个或多个单位，并通过 x402 信封按每单位 $0.001 USDC 在 Base L2 上结算。仅支持入站。 默认情况下，ENABLE=true。

品牌色：#C08D23（Pantone 1245 C，蜂巢文明金）。

接口

层	端点	描述
MCP	POST /mcp	JSON-RPC 2.0、Streamable-HTTP，协议 2024-11-05。
发现	GET /.well-known/mcp.json	工具列表和传输元数据。
REST	POST /v1/quota/check	为 DID 扣除单位。余额不足且未提供支付证明时返回 402。
REST	GET /v1/quota/balance?did=…	查询 DID 的剩余配额。
REST	GET /v1/quota/today	UTC 日期账本快照。
REST	GET /v1/quota/estimate?units=N	查询 N 个单位的标价和最低接受金额（USDC）。
健康检查	GET /health	存活状态、定价和收款地址。
根路径	GET /	为浏览器返回 HTML，为 Agent 返回 JSON（根据 Accept 请求头判断）。JSON-LD SoftwareApplication。

工具

名称	层级	费用	描述
quota_check	1	$0.001/单位	通过 x402 为 DID 扣除 N 个单位。
quota_balance	0	免费	查询 DID 的剩余配额。
quota_topup_estimate	0	免费	查询 N 个单位的标价和最低接受金额。

定价和易货底价

定价沿用 hivemorph 的易货模式。每个 402 信封都会同时公布 amount_usd（标价）和 accept_min_usd（底价）。客户端可以提交链上 实付金额在 [floor, asking] 范围内的支付证明，shim 会接受该证明。

默认值均可通过环境变量覆盖：

变量	默认值	备注
QUOTA_CHECK_PRICE_USDC	0.001	每单位标价。
HIVE_X402_FLOOR_PCT_DEFAULT	0.70	底价占标价的比例。
HIVE_X402_FLOOR_MIN_PCT	0.30	硬性最低限制。
HIVE_X402_FLOOR_MAX_PCT	0.95	硬性最高限制。

因此，按默认值，1 个单位的检查会公布 $0.0010 的标价和 $0.0007 的最低接受金额；100 个单位的检查会公布 $0.1000 的标价和 $0.0700 的最低接受金额。底价不会低于标价的 MIN_PCT，也不会 超过 MAX_PCT。

结算

字段	值
链	Base L2
资产	USDC
合约	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
收款方	WALLET_ADDRESS 环境变量，默认值为 0x15184bf50b3d3f52b60434f8942b7d52f2eb436e
验证	针对 BASE_RPC_URL 调用 provider.getTransactionReceipt(tx_hash)，解码发往收款方的 USDC Transfer 日志，将金额相加（单位为 6 位小数），并与 accept_min_usd 比较。
签名（可选）	ethers.verifyMessage(message, signature) 恢复付款方；如果与链上 from 不一致，则拒绝。

不使用模拟数据。链上检查会通过真实 RPC 读取 Base 主网数据。

存储

SQLite 数据库位于 QUOTA_DB_PATH（默认值为 /tmp/quota.db），包含三个表：

• quotas (did, units_purchased, units_consumed, first_seen, last_seen)
• checks (id, did, unit_count, granted, remaining, tx_hash, paid_usdc, ts)
• topups (id, did, units, paid_usdc, tx_hash UNIQUE, payer, ts)

topups 中的 tx_hash 为 UNIQUE，可防止重放，并返回 409。

x402 信封

调用 quota_check 时，如果没有预付余额且未提供支付证明，则会返回：

{
  "error": "payment_required",
  "x402_version": 1,
  "payment": {
    "nonce": "…",
    "amount_usd": 0.001,
    "accept_min_usd": 0.0007,
    "accepts": [{
      "chain": "base",
      "asset": "USDC",
      "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "recipient": "0x15184bf50b3d3f52b60434f8942b7d52f2eb436e",
      "scheme": "exact"
    }],
    "expires_at": 1761600000,
    "tier": 1,
    "product": "agent_quota_check",
    "unit_count": 1,
    "price_per_unit_usd": 0.001,
    "floor_pct": 0.70
  }
}

客户端向 Base 上的收款方发送 USDC，然后使用包含支付证明的 X-Payment 请求头重新提交相同请求：

X-Payment: {"nonce":"…","chain":"base","tx_hash":"0x…","payer":"0x…","signature":"0x…","message":"hive-quota:<nonce>"}

signature 和 message 均为可选项。如果提供，恢复出的地址必须与 payer 和链上 from 一致。

环境

变量	默认值	说明
PORT	3000
ENABLE	true	设置为 false 可禁用 tools/call。
WALLET_ADDRESS	0x15184bf50b3d3f52b60434f8942b7d52f2eb436e	Base 上的 USDC 接收方。
QUOTA_CHECK_PRICE_USDC	0.001	每单位报价。
HIVE_X402_FLOOR_PCT_DEFAULT	0.70
HIVE_X402_FLOOR_MIN_PCT	0.30
HIVE_X402_FLOOR_MAX_PCT	0.95
BASE_RPC_URL	https://mainnet.base.org
DEFAULT_QUOTA_UNITS	0	首次发现某个 DID 时赠送的免费额度单位数。
QUOTA_DB_PATH	/tmp/quota.db

本地运行

npm install
node server.js

然后：

curl -s http://localhost:3000/health
curl -s -X POST http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -s 'http://localhost:3000/v1/quota/today'

硬性规则

• 仅处理入站支付。该 shim 不会发起出站支付。
• 仓库中不包含私钥。验证为只读操作。
• 不托管资金。接收地址属于运营方，而非 shim。
• 在 BASE_RPC_URL 确认链上收据之前，返回结果仅供参考。

议会溯源

Tier A 第 3 位。2026-04-27。入站计量界面，与 hive-mcp-barter（出站 反报价）和 hive-mcp-auction （入站反向荷兰式拍卖）相对应。

许可证

MIT。请参阅 LICENSE。

Hive 游戏化

此 MCP 服务属于 Hive Civilization 游戏化界面（10 种机制的能力分类体系）。

• 能力分类体系：https://hive-gamification.onrender.com/.well-known/hive-gamification.json
• 离心仪仪表板：https://hive-gamification.onrender.com/.well-known/hive-centrifuge.json
• 汇总 OpenAPI：https://hive-gamification.onrender.com/.well-known/openapi.json

界面标签： gamification.spec.v1 · gamification.surface.public · gamification.signal.read-only · gamification.settlement.real-rails

Base L2 上的真实支付通道（USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913）。只读信号层。品牌金色 #C08D23。

Hive Civilization 目录

属于 Hive Civilization——面向 Agent 的金融基础设施。

• 端点目录：https://thehiveryiq.com
• 实时排行榜：https://hive-a2amev.onrender.com/leaderboard
• 收入仪表板：https://hivemine-dashboard.onrender.com
• 其他 MCP 服务：https://github.com/srotzin?tab=repositories&q=hive-mcp

品牌色：#C08D23