tokeven

Per prompt cost visibility for the Claude, OpenAI, and Google SDKs, without Tokeven ever holding a provider key or seeing a prompt.

tokeven wraps the official provider SDKs. Your call goes to the provider exactly as before, and the wrapper reads the usage block off the response and pushes a small metrics event to your Tokeven dashboard. It also answers the question that saves the most money, which is what a call is about to cost before you send it.

• Website: https://tokeven.com
• Documentation: https://tokeven.com/docs
• Pricing: https://tokeven.com/pricing
• Free teardown tool, no account needed: https://tokeven.com/teardown

Thirty seconds, no install, no account

uvx tokeven teardown

Reads the Claude Code session logs already on your machine, prices them against live rates, and prints what you have actually been spending. It makes zero network calls and asks for nothing. Paste the output at https://tokeven.com/teardown for the breakdown by model, or keep it local.

What it does

• Estimates cost and confidence across all three providers before you send a call, so model choice is an informed decision rather than a default.
• Records what each call actually cost, with cache aware pricing recomputed server side.
• Runs as an MCP server, so Claude Code can ask for an estimate directly.
• Ships a live cost widget for your shell prompt or status line, and a self hosted sidecar for capturing usage without an SDK wrapper.
• Suggests cheaper models and prompt level efficiency improvements, and always leaves the decision to you. Nothing is rerouted silently.

Privacy

• Tokeven receives token counts and metadata such as model, latency, and a character count computed locally. Prompt and completion content never reaches Tokeven through this pipeline.
• Every outgoing event passes a strict key allowlist, so content cannot be transmitted by accident.
• Authentication to Tokeven uses a write only ingest token, which cannot read your data or manage your account. It is not a provider key, and Tokeven never asks for one.
• tokeven reconcile reads your provider's billing report with a provider ADMIN key. That key is read from this machine's environment, used here, and never transmitted. Tokeven has no endpoint that accepts it. Only daily totals are sent.
• TOKEVEN_ACTOR is opt in and off by default. If you set it, the label you choose is attached to your events so your team can see who drives spend. It is a label you pick, not something derived from your prompts.
• Two features are opt in exceptions that do send prompt text you explicitly hand them, because rewriting a prompt requires reading it: the prompt revision tool on the website and advisor.improve(). Both are disclosed at the point of use. Details at https://tokeven.com/privacy
• If any part of the instrumentation fails, your provider call is returned unchanged. Tokeven is designed not to break your application.

Install

pip install tokeven                  # wrapper, advisor, CLI, widget
pip install "tokeven[anthropic]"     # with the Anthropic SDK
pip install "tokeven[openai]"        # with the OpenAI SDK
pip install "tokeven[google-genai]"  # with the Google SDK
pip install "tokeven[xai]"           # for xAI / Grok (uses the OpenAI SDK)
pip install "tokeven[mcp]"           # with the MCP server
pip install "tokeven[proxy]"         # with the self hosted sidecar
pip install "tokeven[all]"           # everything

Requires Python 3.11 or newer. On 3.10 and older pip reports no matching distribution rather than a version error.

For the command line tools on their own, without touching a project environment:

pipx install tokeven

Quickstart

Wrap your existing provider client. Configuration is read from the environment: TOKEVEN_INGEST_TOKEN, TOKEVEN_BASE_URL, TOKEVEN_PROJECT, TOKEVEN_MODE, TOKEVEN_ACTOR.

from anthropic import Anthropic
from tokeven import TokevenAnthropic

client = TokevenAnthropic(Anthropic(), project="billing-agent")

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content)   # unchanged Anthropic response

client.flush()   # optional: push now instead of on the next background tick

Each event is written to a local durable queue as the call returns, and pending events get a short, bounded push when the interpreter exits (default 2s, TOKEVEN_SHUTDOWN_TIMEOUT_S). flush() and close() are bounded too (default 5s, TOKEVEN_FLUSH_TIMEOUT_S). If Tokeven is unreachable, nothing blocks your process and nothing is lost: the queue is sent on the next run.

TokevenOpenAI and TokevenGemini wrap the OpenAI and Google SDKs the same way. Async clients work too: wrap(AsyncAnthropic()), wrap(AsyncOpenAI()), and client.aio on a wrapped genai.Client, including streaming.

For xAI / Grok, use TokevenXAI. Grok is served over the OpenAI SDK against api.x.ai, so there is no separate xAI package to install:

from tokeven import TokevenXAI

client = TokevenXAI(project="research-agent")   # reads XAI_API_KEY

resp = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "Hello"}],
)

wrap() recognises Grok too, including a client you built yourself:

from openai import OpenAI
from tokeven import wrap

client = wrap(OpenAI(base_url="https://api.x.ai/v1", api_key="..."))

Two Grok pricing quirks worth knowing, both handled for you: cached input is priced per model rather than as one family-wide discount, and every Grok model charges double — input and output — once a prompt reaches 200,000 tokens.

First run

Set your write only ingest token:

export TOKEVEN_INGEST_TOKEN="tkv_ing_..."
export TOKEVEN_BASE_URL="https://api.tokeven.com"

Create a token at https://tokeven.com/settings/tokens

Estimate the cost of a call before you send it:

tokeven estimate --model claude-opus-4-8 "your prompt here"

The estimate runs entirely on your machine and needs no account at all.

Use it from Claude Code (MCP)

The advisor runs as an MCP server, so Claude can price a call before it makes one. It is listed in the MCP registry as com.tokeven/tokeven, or add it by hand:

claude mcp add tokeven -- uvx --with 'mcp>=2.0,<3.0' tokeven mcp

tokeven mcp and tokeven-mcp are the same server; the subcommand form is what registry installs launch.

The MCP server estimates and advises. It does not track: nothing it does emits a usage event, because wrap() and the sidecar are the only capture paths. tokeven status reports which of those are actually live on this machine.

Is it actually tracking? (tokeven status)

Instrumentation that is configured but inert looks exactly like instrumentation that works, so there is one command that says which it is:

tokeven status

It reports which capture paths are live (and that the MCP server is an estimator, not a tracker), the resolved base_url and where that value came from, the ingest token prefix and its source, whether base_url is reachable, how many events are sitting undelivered in the local durable queue, and a plain verdict on whether anything is being tracked right now. It needs no login, works offline (--offline skips the reachability probes), never prints your full token, and exits non zero when it finds problems so you can use it in a script. --json gives the same report machine readably.

The sidecar (optional)

If you would rather not wrap an SDK, run the self hosted sidecar and point your provider base URL at it. It forwards every request to the provider verbatim and captures usage on a fail open side channel. Provider keys and prompt content never reach Tokeven.

pip install "tokeven[proxy]"
tokeven-proxy

Point each SDK at the proxy in place of its provider:

Grok is namespaced because xAI serves OpenAI's exact paths, so the proxy has no other way to tell the two apart. It costs nothing: reaching api.x.ai already requires a custom base URL. The /xai segment is stripped before forwarding, so xAI sees the request your SDK built.

A container image and an example docker-compose.yml ship alongside this package.

The live cost widget (optional)

A one line spend gauge for your shell prompt, tmux, or editor status line. It reuses your dashboard login, never an ingest token or a provider key.

tokeven-widget            # print one status line and exit
tokeven-widget watch      # poll and reprint on an interval

What is and is not tracked

Tokeven sees the traffic you instrument. Calls made through the provider consoles, through the Anthropic Workbench, or from applications you have not wrapped will not appear on the dashboard.

tokeven reconcile tells you how big that gap actually is. It reads your provider's own daily cost report and pushes the totals, so the dashboard can show what fraction of your real bill Tokeven can see instead of just warning you that some of it is missing.

export ANTHROPIC_ADMIN_KEY=...      # or OPENAI_ADMIN_KEY; stays on this machine
tokeven reconcile --days 30         # add --dry-run to look before sending

Anthropic and OpenAI expose a billing API to an organization admin key. Google's cost data lives in Cloud Billing exports and xAI has no equivalent endpoint, so for those, export a CSV from the provider console:

tokeven reconcile --csv billing.csv --provider google

Who is spending it

By default the only link from a call to a person is the ingest token that pushed it, so a team sharing one token — or a CI pipeline — shows up as a single anonymous bucket. Set TOKEVEN_ACTOR to label calls:

export TOKEVEN_ACTOR="zoe@example.com"   # or "zoe", or "build-agent-7"

If the label matches a team member's email, the dashboard attributes the spend to them; if it matches nobody, it is reported under the label itself rather than guessed at. Opt in, and unset by default.

Free and paid

Everything this package does on your machine is free, and there is no trial clock on it. That includes pre send cost estimates, the model picker, efficiency suggestions, the MCP server, the sidecar, and the live cost widget. A free Tokeven account adds a dashboard covering 1,000 tracked calls per month.

The paid tier is priced as gainshare. Tokeven earns 10 percent of verified savings, measured per call against live token prices rather than a frozen baseline, and you keep the other 90 percent. If you save nothing, you pay nothing, and the fee falls automatically when model prices fall. There is no per seat charge.

Paid adds:

• Unlimited tracked calls
• Prompt revision suggestions
• Organization wide savings dashboard and per person savings tracking
• Analytics across all three providers
• Embeddable widgets
• n8n and webhook integrations
• CSV, JSON, and API export

Enterprise terms, including capped arrangements for teams that budget fixed line items, SSO, and custom retention, are handled case by case.

If you are weighing the paid tier or want a hand sizing what you would actually save, email team@tokeven.com. We are happy to look at your numbers with you, and there is no obligation attached to asking. Full pricing detail is at https://tokeven.com/pricing

License

Proprietary. The full terms ship in the LICENSE file bundled with this package. Questions: team@tokeven.com