Getting Started

TokenGuard Documentation

TokenGuard is a real-time AI cost monitoring SDK. Wrap your existing OpenAI, Anthropic, or Gemini calls with one line of code and instantly see what every feature, model, and customer costs — on a live dashboard.

⚡ 5 minute setup

Most developers are up and running in under 5 minutes. You don't need to change your existing AI code — just wrap it.

Quick start

Three steps to get TokenGuard tracking your AI costs.

Step 1 — Install the SDK

terminal
npm install @tokenguard/sdk

Step 2 — Get your project key

Sign in to your TokenGuard dashboard, go to Settings, and copy your project key. It looks like this: tg_live_abc123xyz

Step 3 — Wrap your AI call

typescript

// Before TokenGuard
const res = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
})

// After TokenGuard — just wrap it
import { track } from "@tokenguard/sdk"

const res = await track(
  openai.chat.completions.create({ model: "gpt-4o", messages }),
  {
    projectKey: "tg_live_abc123xyz",
    feature: "email-composer",   // optional but recommended
    customer: user.id,              // optional but recommended
  }
)

// res is identical to the original response — nothing changes

Zero latency impact

The track() function passes the API call through unchanged. Logging happens asynchronously in the background — your users never experience any added delay.

Installation

TokenGuard works with npm, yarn, and pnpm.

npm
npm install @tokenguard/sdk

yarn
yarn add @tokenguard/sdk

pnpm
pnpm add @tokenguard/sdk

Requirements

Node.js 18+ required. Works in any environment that supports fetch — Next.js, Express, Cloudflare Workers, Vercel Edge Functions, and more.

track()

The core function. Wraps any AI API call and tracks its cost asynchronously.

typescript
function track<T>(
  promise: Promise<T>,
  options: TrackOptions
): Promise<T>

Returns exactly what the original API call returns. The return type is identical — TypeScript types are preserved.

Options

The second argument to track() accepts these options:

Parameter	Type	Required	Description
projectKey	string	Required	Your TokenGuard project key. Found in Settings → Project key. Starts with `tg_live_`
feature	string	Optional	A label for which feature made this call. Examples: `"email-composer"`, `"chat"`, `"summarize"`. Shows in the Cost by Feature chart.
customer	string	Optional	Your customer's ID. Can be any string — their user ID, email, or org ID. Shows in the Cost per Customer table and enables profitability tracking.

Pro tip

Always pass both feature and customer if you can. The most powerful TokenGuard features — per-customer profitability and model swap suggestions — require this data.

Supported providers

TokenGuard automatically detects the model from the API response and calculates cost using current pricing tables.

OpenAI

gpt-4o
gpt-4o-mini
gpt-4-turbo
gpt-3.5-turbo

SUPPORTED

Anthropic

claude-3-5-sonnet
claude-3-5-haiku
claude-3-opus
claude-3-sonnet

SUPPORTED

Google Gemini

gemini-1.5-pro
gemini-1.5-flash
gemini-1.0-pro

SUPPORTED

Mistral

mistral-7b
mistral-8x7b
mistral-large

SUPPORTED

Cohere

command-r
command-r-plus

COMING SOON

Custom models

Any model that returns token usage in the response

SUPPORTED

Pricing updates

TokenGuard pricing tables are updated weekly as providers change their rates. You never need to update your code — pricing is handled server-side.

Project key

Your project key identifies your project in TokenGuard. Every event logged by the SDK is tagged with this key.

Finding your project key

Go to your dashboard → Settings → SDK Integration. Your key is shown there ready to copy.

Keep it safe

Never commit your project key to a public GitHub repo. Store it in an environment variable: TOKENGUARD_PROJECT_KEY=tg_live_...

best practice
// .env.local
TOKENGUARD_PROJECT_KEY=tg_live_abc123xyz

// your code
const res = await track(openai.chat.completions.create({...}), {
  projectKey: process.env.TOKENGUARD_PROJECT_KEY,
})

Feature tracking

The feature parameter lets you see which parts of your app cost the most. Use short, descriptive names.

typescript
// Email feature
await track(openai.chat.completions.create({...}), {
  projectKey: "tg_live_...",
  feature: "email-composer",
})

// Summarize feature
await track(anthropic.messages.create({...}), {
  projectKey: "tg_live_...",
  feature: "summarize-thread",
})

Your dashboard will show a cost breakdown by feature so you can see which ones are expensive and which ones are candidates for a cheaper model.

Customer attribution

Pass a customer ID to see exactly how much each of your customers costs you — and whether they are profitable on your current plan.

typescript
// Pass your customer's ID
await track(openai.chat.completions.create({...}), {
  projectKey: "tg_live_...",
  feature: "chat",
  customer: user.id,    // any unique string
})

The dashboard will show each customer's total AI cost alongside their plan price, so you can instantly see who is profitable and who is costing you money.

Usage-based pricing

If you charge customers based on usage, customer attribution is essential. You can export this data as CSV from the Customers page for billing.

Budget alerts

Set a monthly budget in Settings and TokenGuard will alert you before you exceed it. Alerts fire at 80% and 100% of your budget by default.

Alerts are sent via:

Slack webhook
Discord webhook
Email (daily digest)

Configure alert channels in Settings → Alerts. No code changes required — alerts are configured entirely in the dashboard.

Example: OpenAI

typescript

import OpenAI from "openai"
import { track } from "@tokenguard/sdk"

const openai = new OpenAI()

export async function generateEmail(prompt: string, userId: string) {
  const response = await track(
    openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: prompt }],
    }),
    {
      projectKey: process.env.TOKENGUARD_PROJECT_KEY!,
      feature: "email-composer",
      customer: userId,
    }
  )
  return response.choices[0].message.content
}

Example: Anthropic

typescript

import Anthropic from "@anthropic-ai/sdk"
import { track } from "@tokenguard/sdk"

const anthropic = new Anthropic()

export async function summarize(text: string, userId: string) {
  const response = await track(
    anthropic.messages.create({
      model: "claude-3-5-haiku-20241022",
      max_tokens: 1024,
      messages: [{ role: "user", content: text }],
    }),
    {
      projectKey: process.env.TOKENGUARD_PROJECT_KEY!,
      feature: "summarize-thread",
      customer: userId,
    }
  )
  return response.content[0].text
}

Example: Google Gemini

typescript

import { GoogleGenerativeAI } from "@google/generative-ai"
import { track } from "@tokenguard/sdk"

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!)

export async function translate(text: string, userId: string) {
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" })
  const response = await track(
    model.generateContent(text),
    {
      projectKey: process.env.TOKENGUARD_PROJECT_KEY!,
      feature: "translate",
      customer: userId,
    }
  )
  return response.response.text()
}

Example: Next.js API route

typescript — app/api/chat/route.ts

import { NextResponse } from "next/server"
import OpenAI from "openai"
import { track } from "@tokenguard/sdk"

const openai = new OpenAI()

export async function POST(req: Request) {
  const { message, userId } = await req.json()

  const response = await track(
    openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: message }],
    }),
    {
      projectKey: process.env.TOKENGUARD_PROJECT_KEY!,
      feature: "chat",
      customer: userId,
    }
  )

  return NextResponse.json({
    reply: response.choices[0].message.content
  })
}

FAQ

Does track() slow down my AI calls?

No. The track() function awaits the original API call and returns the result immediately. Logging happens asynchronously in a fire-and-forget background call. If logging fails for any reason, your AI call is completely unaffected.

What happens if TokenGuard's servers are down?

Your AI calls continue working normally. The SDK catches all errors silently — if the logging request fails, it fails quietly without throwing or affecting your application.

How accurate is the cost calculation?

Very accurate. TokenGuard reads the actual token counts from the API response (input_tokens and output_tokens) and multiplies by current pricing. Pricing tables are updated weekly. You can see the exact calculation in the dashboard.

Can I use TokenGuard with multiple AI providers at once?

Yes. Just wrap each provider's calls with track(). TokenGuard auto-detects the model from the response and uses the correct pricing. Your dashboard will show a unified view across all providers.

Is my data secure?

TokenGuard only logs metadata — token counts, model name, cost, feature tag, and customer ID. We never log the content of your prompts or responses. All data is stored in a private Supabase database with row-level security.

Can I export my data?

Yes. On the Pro and Team plans, you can export all usage data as CSV from the Customers and Features pages. Useful for billing, accounting, and further analysis.

What if my model isn't in the pricing table?

TokenGuard will still log the event with 0 cost and flag it as an unrecognized model. Contact us at hello@tokenguards.com and we'll add it in the next weekly update.

Troubleshooting

Events not appearing in dashboard

Check these in order:

Is your projectKey correct? Copy it fresh from Settings.
Is the SDK installed? Run npm list @tokenguard/sdk
Are you in test/mock mode? Make sure real API calls are being made.
Check your network tab — you should see a POST to api.tokenguard.workers.dev

TypeScript errors

fix
// If you get type errors, make sure you're on TypeScript 4.7+
npm install typescript@latest --save-dev

Still stuck?

Email us at hello@tokenguards.com with your project key (not your secret key) and a description of the issue. We respond within 24 hours.