TokenGuard · Developer guide

Use TokenGuard in 5 minutes

TokenGuard sits between your app and LLM providers. It enforces budgets and stops agent loops before money is spent. Auth stays strong: admin secret for management, tg_ keys for apps, provider keys for upstream.

Open developer console Machine-readable API map Health check

1. What changes in your app

BEFORE  App ──► OpenAI / OpenRouter / Anthropic
AFTER   App ──► TokenGuard ──► provider

Keep your provider API key. Add a TokenGuard user key. Point the SDK base URL at the API host (https://token-guard.site).

2. Create a user key

Open the developer console or product portal.
Console: unlock with TOKENGUARD_ADMIN_SECRET. Portal: sign in with Clerk.
Provision / create a key → copy the one-time tg_... key.

Or POST /mgmt/provision with header X-TokenGuard-Admin-Secret.

3. Call the proxy

Required on every LLM request:

Header	Value
X-TokenGuard-API-Key	Your `tg_...` key
Authorization / x-api-key	Real provider key (passed through)
X-TokenGuard-Provider	openai · openrouter · anthropic
X-TokenGuard-Session-ID	Stable id per agent run (loop protection)

curl -s https://token-guard.site/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PROVIDER_KEY" \
  -H "X-TokenGuard-API-Key: tg_YOUR_KEY" \
  -H "X-TokenGuard-Provider: openrouter" \
  -H "X-TokenGuard-Session-ID: dev-session-1" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'

4. SDK pattern (OpenAI-compatible)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: "https://token-guard.site/v1",
  defaultHeaders: {
    "X-TokenGuard-API-Key": process.env.TOKENGUARD_API_KEY,
    "X-TokenGuard-Provider": "openrouter",
    "X-TokenGuard-Session-ID": "my-app-1",
  },
});

5. Status codes you should handle

Code	Meaning
401	Missing/invalid `tg_` key
400	Bad body or model not in pricing
402	Budget exceeded
409	Agent loop detected
503	Billing/Redis unavailable

JSON errors include a machine code field (e.g. budget_exceeded).

Useful URLs

https://token-guard.site/docs (this page)/dashboard/portal/v1/tokenguard.json/v1/status/mgmt/*

Deeper docs in the repo