Gvnr

Gvnr

为 AI Agent 设置支出上限、协调速率、实现幂等性，并加入人工参与审核环节——在调用前执行管控，而不是等到账单寄来后。 一个 MCP 端点，通过 x402（Base 上的 USDC）结算。无需代理、无需自行托管，也无需部署基础设施。

已列入官方 MCP Registry，名称为 dev.gvnr/gvnr。

---

问题

Agent 在生产环境中的成本比预估高出 10–12 倍。系统提示词、重试循环和工具调用会迅速叠加——失控的 Agent 可能在 11 天内产生 47,000 美元的账单。常见的解决方案是自行托管 LiteLLM 之类的网关，但这意味着要运行大多数开发者都不愿设置的基础设施。

Gvnr 是一种托管式替代方案：一个外部权威服务，Agent 在支出前向它查询。Agent 会询问“我可以进行这次调用吗？”，并根据答复采取行动。

---

工作原理

Gvnr 不是 LLM 代理——你的令牌不会经过它，你直接向模型提供商付费。Gvnr 管控的是支出的决策，通过两个互相独立的计量项实现：

1. 治理操作配额——你向 Gvnr 购买的内容。 你的账户持有一定余额的治理操作（operations_remaining）。每次 budget_clear 会消耗 1 个操作。你使用 USDC 为其充值；它与 LLM 支出相互独立。get_balance 会报告其余额。

2. 支出额度——由你为每个 Agent 设置的美元上限。 set_envelope(agent_id, limit_usd, window) 为 Agent 设置每日或每次会话的美元上限。Gvnr 会跟踪预估支出，超过上限后即予以拒绝——这就是防止失控的安全措施。不会有资金转移；这只是由你控制的记账上限。

只有在同时满足以下条件时，budget_clear 才会获批：账户配额中仍有可用操作，且 Agent 的支出未超过额度。流程如下：

1. Agent 在每次 LLM 请求前调用 budget_clear(agent_id, model, estimated_tokens)。
2. Gvnr 检查操作配额和 Agent 的支出额度，并返回 { approved: true, ... } 或 { approved: false, reason }。
3. 如果请求被拒绝，Agent 会跳过调用（或通过 request_approval 请求升级审批）。
4. LLM 返回响应后，调用 reconcile(...) 并传入实际令牌数，以便额度跟踪实际费用，而非预估费用。

---

快速开始

1. 创建账户

curl -X POST https://gvnr.dev/v1/account
# { "api_key": "bg_...", "account_id": "...", "operations_remaining": 25 }

新账户包含 25 个免费试用操作——在充值前，足以完整运行整个流程（设置额度、调用 budget_clear、调用 reconcile）。你的 api_key 是每次调用所需的凭证；account_id 仅供支持团队内部查询。账户创建仅需凭证（原生支持 Agent），这是有意的设计——电子邮件为可选项，需另行通过 POST /v1/account/notification-email 设置，仅用于发送人工审批通知。

2. 为治理操作配额充值

按使用量付费：每 1 美元可购买 1,000 个操作，金额不限（可用 1 美元试跑全流程），使用 Base 上的 USDC。打开付款页面，输入金额并提供 API 密钥：

https://gvnr.dev/pay?usd=1&api_key=bg_YOUR_KEY

向页面显示的地址发送 USDC，然后粘贴交易哈希——链上验证完成后，操作数将按收到的金额比例入账。程序化客户端也可以直接提交哈希：

curl -X POST \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tx_hash":"0x..."}' \
  https://gvnr.dev/v1/account/topup-verify
# { "operations_remaining": 1000, "credited_ops": 1000, "credited_usd": 1 }

也可以使用 x402 客户端（Base MCP、AgentKit、x402-fetch）一次往返完成结算——金额由你指定：

POST https://gvnr.dev/v1/account/topup?usd=5      # → 402 challenge → pay → 5,000 ops credited

3. 为你的 Agent 设置支出额度

curl -X PUT \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","limit_usd":5,"window":"daily"}' \
  https://gvnr.dev/v1/budget/envelope
# { "success": true, "agent_id": "my-agent", "limit_usd": 5, "window": "daily" }

4.（可选）为每个（Agent、提供商、模型）设置速率额度

curl -X PUT \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","provider":"anthropic","model":"claude-sonnet-4-6","requests_per_minute":30}' \
  https://gvnr.dev/v1/rate/envelope

5. 每次 LLM 请求前：先调用 budget_clear，再调用 rate_check

curl -X POST \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","model":"claude-sonnet-4-6","estimated_tokens":2000}' \
  https://gvnr.dev/v1/budget/clear
# { "approved": true, "remaining_usd": 4.994, "operations_remaining": 18999 }

curl -X POST \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","provider":"anthropic","model":"claude-sonnet-4-6"}' \
  https://gvnr.dev/v1/rate/check
# { "allowed": true, "requests_remaining_this_minute": 29 }

6.（可选）使用 idempotency_check 去重重试

curl -X POST \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"job-abc-123","ttl_seconds":3600}' \
  https://gvnr.dev/v1/idempotency/check
# First call:  { "is_first_call": true,  "ttl_remaining_seconds": 3600 }
# Replay:      { "is_first_call": false, "ttl_remaining_seconds": 3598 }

7. LLM 响应后，根据实际用量进行结算

curl -X POST \
  -H "Authorization: Bearer bg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","actual_input_tokens":1800,"actual_output_tokens":2400}' \
  https://gvnr.dev/v1/budget/reconcile
# { "ok": true, "drift_usd": 0.003, "remaining_usd": 4.991, "operations_remaining": 18999 }

reconcile 会根据估算成本与实际成本之间的偏差调整支出额度（操作配额不受影响）。无需再次传入模型——reconcile 会复用你之前调用 budget_clear 时使用的模型。Anthropic、OpenAI 和 Gemini 都会在 usage 字段中返回实际令牌数——传入这些数据，即可确保额度准确反映实际情况。

---

人机审批

当 Agent 遭到拒绝或需要执行敏感操作时，可以暂停并请求人工审批，而不是直接失败：

# 1. Open a request — returns an approval_id and a mobile-friendly approval_url
curl -X POST -H "Authorization: Bearer bg_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","action_summary":"Spend $40 on a research run","ttl_seconds":3600}' \
  https://gvnr.dev/v1/approval/request
# { "approval_id": "...", "approval_url": "https://gvnr.dev/approve/...", "expires_at": ... }

# 2. The human opens approval_url and taps approve / deny (emailed if notification-email is set).

# 3. Your agent polls until the decision lands:
curl -H "Authorization: Bearer bg_YOUR_KEY" \
  https://gvnr.dev/v1/approval/check/APPROVAL_ID
# { "decision": "pending" }  →  "approved" | "denied" | "timeout"

Agent 收到 approved 后继续执行，收到 denied 后跳过，并可自行处理 timeout（在 expires_at 之前未收到决定）。

---

MCP 设置

添加到 Claude Desktop 或任何兼容 MCP 的客户端：

https://gvnr.dev/mcp?api_key=bg_YOUR_KEY

Claude Code

claude mcp add gvnr --transport http \
  "https://gvnr.dev/mcp?api_key=bg_YOUR_KEY"

MCP 工具

工具	描述
budget_clear(agent_id, model, estimated_tokens)	检查是否符合操作配额和支出额度；消耗一次操作配额
set_envelope(agent_id, limit_usd, window?)	创建或更新 Agent 的美元支出上限
get_balance()	剩余的治理操作配额（operations_remaining）
reconcile(agent_id, actual_input_tokens, actual_output_tokens)	LLM 响应后，将估算值与实际值之间的偏差计入支出额度
set_rate_envelope(agent_id, provider, model, requests_per_minute)	为每个（Agent、提供商、模型）分配速率额度
rate_check(agent_id, provider, model)	根据速率额度批准或拒绝；拒绝时返回 retry_after_ms
idempotency_check(key, ttl_seconds?)	使用调用方提供的键对重试进行去重；返回 is_first_call
request_approval(agent_id, action_summary, ttl_seconds?)	发起人工审批请求；返回 approval_id
check_approval(approval_id)	轮询审批状态：pending / approved / denied / timeout

---

REST API

除 POST /v1/account 外，所有端点都需要 Authorization: Bearer bg_YOUR_KEY。

TypeScript 用户： 根据在线 OpenAPI 规范生成完整类型：npx openapi-typescript@latest https://gvnr.dev/openapi.json -o types/gvnr.d.ts。有关集成方式（类型化的 fetch、x402 充值、判别式响应联合类型），请参阅 TYPESCRIPT.md。

账户与充值

方法	路径	描述
POST	/v1/account	创建账户——返回 api_key
GET	/v1/account/balance	剩余的治理操作配额（operations_remaining）
GET	/v1/packs/:pack/info	公开信息——预设详情、USDC 地址、原始金额
POST	/v1/account/topup-verify/:pack	提交交易哈希 → 链上验证 → 入账（按实际收到的金额比例计算）
POST	/v1/account/topup?usd=<amount>	受 x402 保护的按需充值——自行指定金额（最低 $1，最高 $100）
POST	/v1/account/topup/:pack	受 x402 保护的预设充值（机器客户端）

预算

方法	路径	描述
POST	/v1/budget/clear	额度检查调用——批准或拒绝
POST	/v1/budget/reconcile	将估算值与实际值之间的偏差计入额度
PUT	/v1/budget/envelope	创建或更新 Agent 支出上限
GET	/v1/budget/envelope/:agent_id	读取额度状态
DELETE	/v1/budget/envelope/:agent_id	删除 Agent 的额度

费率 · 幂等性 · 审批

方法	路径	说明
PUT	/v1/rate/envelope	设置每个（Agent、提供商、模型）的 RPM 份额
POST	/v1/rate/check	运行时费率检查——拒绝时返回 allowed 标志和 retry_after_ms
POST	/v1/idempotency/check	根据调用方提供的键去重——返回 is_first_call
POST	/v1/approval/request	发起人工审批请求——返回 approval_id
GET	/v1/approval/check/:approval_id	轮询审批结果：pending / approved / denied / timeout

额度检查响应

{ "approved": true, "remaining_usd": 4.994, "operations_remaining": 18999 }

{ "approved": false, "remaining_usd": 0, "reason": "envelope_exceeded" }

拒绝原因：no_credits（操作额度已用尽） · no_envelope（Agent 没有额度包） · envelope_exceeded

状态码

拒绝不属于 HTTP 错误——它会以带标志的 200 响应返回，因此请检查响应正文，而非状态码：

情况	HTTP	正文
budget_clear / rate_check 允许 或 拒绝	200	{ approved/allowed: true | false, ... }
充值需要付款	402	x402 挑战（位于 payment-required 标头中；请参阅“计费”）
API 密钥缺失 / 无效	401	{ error }
按 IP 限制创建账户的频率	429	{ error: "rate_limited", retry_after_ms }
请求正文格式错误	400	{ error, hint }

---

计费——治理操作，而非你的令牌

Gvnr 按治理操作收费，而非按 LLM 用量收费。模型令牌由你的提供商计费；Gvnr 不会接触这些令牌。

充值采用按用量付费，1 美元兑换 1,000 次操作，使用 Base 主网上的 USDC——在 /pay 输入任意金额，经链上验证后，操作额度会按比例到账。无最低金额，也无订阅；以下金额只是可一键选择的预设：

金额	治理操作次数	链接
$1（试用）	1,000	/pay?usd=1
$19	19,000	/pay?usd=19
$39	39,000	/pay?usd=39
$79	79,000	/pay?usd=79

支持 Base MCP、AgentKit，以及任何 x402 客户端。402 挑战遵循 x402 v2——付款要求（网络、USDC 资产、金额、payTo）会通过 payment-required 响应标头返回（正文为空），因此 x402 客户端会自动完成结算；只有自行实现时才需要手动解析。

---

额度包窗口

• daily — 每天 UTC 午夜重置
• session — 永不重置（用于一次性任务；由调用方管理）

---

支持的模型

模型定价是在热路径上的静态查找，不会进行外部调用。从额度包中扣除的预估值为 rate(model) × estimated_tokens ÷ 1,000,000（聊天模型使用输出费率，嵌入模型使用输入费率），之后会按实际用量结算。以下是每百万令牌的费率（美元）：

模型	输入	输出
claude-opus-4-8 / 4-7 / 4-6	$5	$25
claude-sonnet-4-6	$3	$15
claude-haiku-4-5	$1	$5
gpt-4o	$2.50	$10
gpt-4o-mini	$0.15	$0.60
gpt-4-turbo	$10	$30
text-embedding-3-small / -large	$0.02 / $0.13	仅输入
gemini-embedding-001 / -2	$0.15 / $0.20	仅输入

嵌入 / 仅输入模型按输入令牌计费——将输入令牌数作为 estimated_tokens 传给 budget_clear。未知模型会回退到较为保守的 $15 / $75 默认值。

---

网络

运行于 Base 主网（X402_NETWORK=eip155:8453），使用真实 USDC 结算。试用没有最低金额：只需充值 $1（1,000 次治理操作），即可端到端体验完整的实时支付流程——无需测试网。

---

许可证

MIT — 请参阅 LICENSE。

官方托管服务为 https://gvnr.dev。自托管实例与官方服务无关。

---

致谢

gvnr 由 mightbesaad 与 Claude Code（Anthropic）紧密合作设计并构建，主要使用 Claude Opus 4.8。从底层架构和计费模式，到此代码库中的代码，这都是真正的协作成果。感谢。