Gvnr

Gvnr

AI エージェント向けに、支出上限、レート調整、冪等性、human-in-the-loop の承認ゲートを提供します — 請求後ではなく、呼び出し前に適用されます。 x402（Base 上の USDC）で決済される、単一の MCP エンドポイントです。プロキシもセルフホスティングも、デプロイするインフラも不要です。

Official MCP Registry に dev.gvnr/gvnr として登録されています。

---

課題

本番環境では、エージェントのコストが見積もりの 10～12 倍になります。システムプロンプト、リトライループ、ツール呼び出しによって費用は急速に膨らみ、暴走したエージェントが 11 日間で 47,000 ドルの請求を発生させることもあります。一般的な解決策である LiteLLM のようなゲートウェイのセルフホスティングでは、多くの開発者が用意しないインフラの運用が必要です。

Gvnr はホスト型の代替手段です。エージェントが支出する前に確認する外部の判断機関です。エージェントは「この呼び出しを実行しても問題ありませんか？」と問い合わせ、その回答に基づいて動作します。

---

仕組み

Gvnr は LLM プロキシではありません。トークンが Gvnr を経由することはなく、モデルプロバイダーに直接支払います。Gvnr は支出の判断を、独立した 2 つのメーターで管理します。

1. ガバナンス操作クォータ — Gvnr から購入するものです。
アカウントにはガバナンス操作の残高（operations_remaining）があります。budget_clear を 1 回呼び出すごとに 1 操作を消費します。USDC で残高を追加します。LLM の利用額とは連動しません。get_balance で確認できます。

2. 支出枠 — エージェントごとにユーザーが設定する USD の上限です。
set_envelope(agent_id, limit_usd, window) で、エージェントに日次またはセッション単位の USD 上限を設定します。Gvnr は見積もり支出額を追跡し、上限を超えると拒否します。これが暴走を防ぐためのガードレールです。金銭の移動はなく、ユーザーが管理する会計上の上限です。

budget_clear が承認されるのは、アカウントにクォータの操作数が残っていて、かつエージェントの支出額が支出枠内にある場合のみです。処理の流れは次のとおりです。

1. エージェントは各 LLM リクエストの前に budget_clear(agent_id, model, estimated_tokens) を呼び出します。
2. Gvnr は操作クォータとエージェントの支出枠を確認し、{ approved: true, ... } または { approved: false, reason } を返します。
3. 拒否された場合、エージェントは処理をスキップするか、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 はサポート用の内部参照にすぎません。アカウントの作成は、エージェントネイティブな設計に基づき認証情報のみで行えます。メールアドレスは任意で、POST /v1/account/notification-email から別途設定し、人間による承認通知にのみ使用します。

2. ガバナンス操作クォータに入金する

従量課金制です。Base 上の USDC で、金額を問わず 1 ドルにつき操作 1,000 回分を購入できます（決済全体の流れを 1 ドルでお試しいただけます）。支払いページを開き、金額を指定して 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）を使って、1 回の往復で決済できます。金額は自由に指定できます。

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

3. エージェントの支出上限を設定する

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. （任意）エージェント、プロバイダー、モデルごとのレート上限を設定する

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 フィールドを返します。これらの値を渡すことで、上限を実態に即した状態に保てます。

---

人間参加型の承認

エージェントが拒否に遭った場合や機微な操作を行おうとする場合は、処理を失敗させるのではなく、人間の判断を待ちます。

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

エージェントは 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)	操作クォータと支出上限に照らして利用可能か確認し、操作を 1 回分消費します
set_envelope(agent_id, limit_usd, window?)	エージェントの米ドル建て支出上限を新規作成または更新します
get_balance()	ガバナンス操作の残りクォータ（operations_remaining）を返します
reconcile(agent_id, actual_input_tokens, actual_output_tokens)	LLM の応答後、推定と実績の差分を支出上限に反映します
set_rate_envelope(agent_id, provider, model, requests_per_minute)	エージェント、プロバイダー、モデルごとのレート上限を割り当てます
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	エージェントの支出上限を新規作成または更新します
GET	/v1/budget/envelope/:agent_id	上限の状態を読み取ります
DELETE	/v1/budget/envelope/:agent_id	エージェントの上限を削除します

レート · 冪等性 · 承認

メソッド	パス	説明
PUT	/v1/rate/envelope	エージェント、プロバイダー、モデルごとの 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

Clearance レスポンス

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

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

拒否理由：no_credits（運用クォータを使い切りました）・no_envelope（エージェントにエンベロープがありません）・envelope_exceeded

ステータスコード

拒否は HTTP エラーではありません。フラグを含む 200 が返るため、ステータスではなく本文を確認してください。

状況	HTTP	本文
budget_clear ／ rate_check が許可 または 拒否	200	{ approved/allowed: true | false, ... }
チャージに支払いが必要	402	x402 チャレンジ（payment-required ヘッダー内。Billing を参照）
API キーがない、または無効	401	{ error }
IP ごとのアカウント作成制限	429	{ error: "rate_limited", retry_after_ms }
リクエスト本文が不正	400	{ error, hint }

---

Billing — トークンではなくガバナンス運用

Gvnr が課金するのはLLMの利用量ではなく、ガバナンス運用です。モデルのトークン料金はプロバイダーから請求され、Gvnr がそのトークンを見ることはありません。

チャージはBaseメインネット上のUSDCで、1ドルあたり1,000運用の従量課金制です。/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の午前0時にリセットされます
• session — リセットされません（単発タスクに使用し、呼び出し元が管理します）

---

対応モデル

モデルの料金は、ホットパスでの静的な参照値であり、外部呼び出しは行いません。エンベロープから差し引かれる推定額は rate(model) × estimated_tokens ÷ 1,000,000 です（チャットモデルには出力レート、埋め込みには入力レートを使用）。その後、実際の使用量に合わせて精算されます。以下は100万トークンあたりの料金（USD）です。

モデル	入力	出力
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	入力のみ

埋め込みモデルなど入力のみのモデルは入力トークンに基づいて課金されます。budget_clear の estimated_tokens には入力トークンを渡してください。不明なモデルには、控えめなデフォルト値 $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と緊密に協力して設計・構築しました。基盤アーキテクチャや課金モデルから、このリポジトリ内のコードに至るまで、真の共同作業によって生まれたものです。ありがとうございました。