Content
# Gvnr
Substrate primitives for AI agents — spend caps, rate limits, idempotency, post-call reconciliation, human approval bridges. One MCP endpoint, one credit pool, no infrastructure to deploy.
Listed on the Official MCP Registry as [`dev.gvnr/gvnr`](https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.gvnr/gvnr).
No deployment. No proxy. No self-hosting.
---
## The problem
Agents cost 10–12x more than estimated in production. System prompts, retry loops, and tool calls multiply fast. A runaway agent can generate a $47,000 bill in 11 days. The common fix — self-hosting LiteLLM — requires running infrastructure most developers won't set up.
Gvnr is the hosted alternative: an external authority your agent checks before spending.
---
## How it works
1. Your agent calls `budget_clear` (MCP tool or REST) before each LLM request
2. The governor checks your account credit balance and the agent's spend envelope
3. It returns `{ approved: true }` or `{ approved: false, reason: "..." }`
4. If denied, your agent skips the call
The envelope is configured by you (per-agent daily or session cap). The credit balance is topped up via USDC on Base.
---
## Quick start
### 1. Provision an account
```bash
curl -X POST https://gvnr.dev/v1/account
# { "api_key": "bg_...", "account_id": "..." }
```
### 2. Top up credits
Open the payment page for your chosen pack, pass your API key as a query param:
```
https://gvnr.dev/pay/starter?api_key=bg_YOUR_KEY
```
Send USDC on Base to the address shown, paste your tx hash — credits are added after on-chain verification.
Or, if you prefer the programmatic path — POST the tx hash directly:
```bash
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/starter
```
### 3. Set a spend envelope for your agent
```bash
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. Set a rate envelope per (agent, provider, model)
```bash
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
# { "success": true, ... }
```
### 5. Before each LLM request: budget_clear then rate_check
```bash
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 }
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. (optional) Dedupe retries with `idempotency_check`
```bash
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. After the LLM responds, reconcile against actual usage
```bash
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, "balance_usd": 9.991 }
```
`reconcile` is optional but keeps the envelope honest — Anthropic, OpenAI, and Gemini all return `usage` fields with the actual token counts; pass those in.
---
## MCP setup
Add to Claude Desktop or any MCP-compatible client:
```
https://gvnr.dev/mcp?api_key=bg_YOUR_KEY
```
### Claude Code
```bash
claude mcp add gvnr --transport http \
"https://gvnr.dev/mcp?api_key=bg_YOUR_KEY"
```
### MCP tools
| Tool | Description |
|---|---|
| `budget_clear(agent_id, model, estimated_tokens)` | Check clearance and deduct estimated cost |
| `set_envelope(agent_id, limit_usd, window?)` | Create or update an agent's spend envelope |
| `get_balance()` | Get current account credit balance |
| `reconcile(agent_id, actual_input_tokens, actual_output_tokens)` | Apply the drift between estimated and actual cost after the LLM responds |
| `set_rate_envelope(agent_id, provider, model, requests_per_minute)` | Allocate a per-(agent, provider, model) rate share |
| `rate_check(agent_id, provider, model)` | Approve or deny based on the rate envelope; returns `retry_after_ms` on denial |
| `idempotency_check(key, ttl_seconds?)` | Dedupe retries on a caller-supplied key; returns `is_first_call` |
---
## REST API
All endpoints (except `POST /v1/account`) require `Authorization: Bearer bg_YOUR_KEY`.
### Account
| Method | Path | Description |
|---|---|---|
| `POST` | `/v1/account` | Provision account — returns `api_key` |
| `GET` | `/v1/account/balance` | Current credit balance |
| `GET` | `/v1/packs/:pack/info` | Public — pack details, USDC address, raw amount |
| `POST` | `/v1/account/topup-verify/:pack` | Submit tx hash → verify on-chain → credit account |
| `POST` | `/v1/account/topup/:pack` | x402-gated credit top-up (machine clients) |
### Budget
| Method | Path | Description |
|---|---|---|
| `POST` | `/v1/budget/clear` | Clearance call — approve or deny |
| `PUT` | `/v1/budget/envelope` | Create or update agent envelope |
| `GET` | `/v1/budget/envelope/:agent_id` | Read envelope state |
### Clearance response
```json
{ "approved": true, "remaining_usd": 4.994 }
```
```json
{ "approved": false, "remaining_usd": 0, "reason": "envelope_exceeded" }
```
Denial reasons: `no_credits` · `no_envelope` · `envelope_exceeded`
---
## Credit packs
Top up at `GET /pay/:pack?api_key=bg_YOUR_KEY`. Send USDC on Base mainnet — credits added after on-chain verification.
| Pack | Price | Clearances | Link |
|---|---|---|---|
| `starter` | $19 | ~10k/month | `/pay/starter` |
| `growth` | $39 | ~30k/month | `/pay/growth` |
| `studio` | $79 | ~100k/month | `/pay/studio` |
---
## Envelope windows
- `daily` — resets at UTC midnight each day
- `session` — never resets (use for one-shot tasks)
---
## Supported models
Model pricing is a static lookup on the hot path — no external calls. Includes claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5, gpt-4o, gpt-4o-mini, and others. Embedding models (text-embedding-3-small/large, gemini-embedding-001/2) are billed input-only — pass input tokens to `budget_clear` for those. Unknown models fall back to a conservative default.
---
## Network
| `X402_NETWORK` | Chain | Notes |
|---|---|---|
| `eip155:84532` | Base Sepolia | Testnet — safe for development |
| `eip155:8453` | Base mainnet | Real USDC |
Current deployment: Base mainnet.
---
## License
MIT — see [LICENSE](LICENSE).
The canonical hosted service is at `https://gvnr.dev`. Self-hosted instances are unaffiliated.
