TokenGuard Developer Documentation

TokenGuard instruments your AI framework using standard client wrappers. It operates asynchronously in the background: your LLM requests execute with zero added user-perceived latency.

Instruments OpenAI chat.completions.create and streaming responses.

import { TokenGuard, wrapOpenAI } from "@tokenguard/sdk";
import OpenAI from "openai";

// 1. Initialize TokenGuard
const tg = new TokenGuard({
  apiKey: process.env.TOKENGUARD_API_KEY!,
  baseUrl: "https://tokenguard-app-two.vercel.app",
});

// 2. Wrap the OpenAI client
const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY! }), tg);

// 3. Normal OpenAI usage (tracked automatically!)
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarize today's news." }],
});

console.log(response.choices[0].message.content);

import os
from tokenguard import TokenGuard, wrap_openai
from openai import OpenAI

# 1. Initialize TokenGuard
tg = TokenGuard(
    api_key=os.environ["TOKENGUARD_API_KEY"],
    base_url="https://tokenguard-app-two.vercel.app"
)

# 2. Wrap client
client = wrap_openai(OpenAI(api_key=os.environ["OPENAI_API_KEY"]), tg)

# 3. Call OpenAI as usual
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain vector databases."}]
)

print(response.choices[0].message.content)

Automatic instrumentation for Claude 3.5 Sonnet, Haiku, and Opus with prompt caching support.

import { TokenGuard, wrapAnthropic } from "@tokenguard/sdk";
import Anthropic from "@anthropic-ai/sdk";

const tg = new TokenGuard({
  apiKey: process.env.TOKENGUARD_API_KEY!,
  baseUrl: "https://tokenguard-app-two.vercel.app",
});

const anthropic = wrapAnthropic(
  new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
  tg
);

const message = await anthropic.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Optimize this SQL query for performance." }],
});

console.log(message.content);

Tracks token counts and costs for Gemini 1.5 Flash, 1.5 Pro, and experimental models.

import { TokenGuard, wrapGemini } from "@tokenguard/sdk";
import { GoogleGenAI } from "@google/genai";

const tg = new TokenGuard({
  apiKey: process.env.TOKENGUARD_API_KEY!,
  baseUrl: "https://tokenguard-app-two.vercel.app",
});

const ai = wrapGemini(
  new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! }),
  tg
);

const response = await ai.models.generateContent({
  model: "gemini-1.5-pro",
  contents: "Explain the differences between dense and sparse retrieval.",
});

console.log(response.text);

For custom workflows with multiple steps (LLM reasoning, vector search, API tools, retries), use manual trace waterfalls:

import { TokenGuard } from "@tokenguard/sdk";

const tg = new TokenGuard({
  apiKey: process.env.TOKENGUARD_API_KEY!,
  baseUrl: "https://tokenguard-app-two.vercel.app",
});

const result = await tg.trace("support-agent", async (trace) => {
  // Step 1: LLM Call
  const llmSpan = trace.llm({ model: "gpt-4o" });
  // ... run LLM ...
  llmSpan.end({
    inputTokens: 350,
    outputTokens: 80,
    request: { prompt: "Lookup order #890" },
    response: { tool: "query_database", id: "890" },
  });

  // Step 2: Database Tool
  const toolSpan = trace.tool("query_database", { arguments: { id: "890" } });
  // ... query DB ...
  toolSpan.end({ result: { status: "Delivered" } });

  return "Order #890 is Delivered.";
});

If you are developing in Go, Rust, Ruby, Elixir, C#, or PHP, send standard HTTP POST requests:

curl -X POST "https://tokenguard-app-two.vercel.app/api/v1/ingest" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "production-service",
    "status": "success",
    "startedAt": "2026-09-25T10:00:00Z",
    "endedAt": "2026-09-25T10:00:02Z",
    "durationMs": 2000,
    "steps": [{
      "stepType": "llm",
      "sequence": 1,
      "startedAt": "2026-09-25T10:00:00Z",
      "endedAt": "2026-09-25T10:00:02Z",
      "durationMs": 2000,
      "llmCall": {
        "modelName": "gpt-4o",
        "inputTokens": 450,
        "outputTokens": 120,
        "requestJson": "{\"prompt\":\"Hello\"}",
        "responseJson": "{\"reply\":\"Hi there\"}"
      }
    }]
  }'