Quickstart

Create a key, route a request, and match the response to its receipt.

Get a key

Create a rail key (your TokenSpend API key, starts with tsr_) in Router. The secret is shown once and authenticates as Authorization: Bearer or x-api-key. Keep it server-side as TOKENSPEND_API_KEY.

Route your first request

Point at the rail. Chat Completions is the shortest path. The registry currently lists 120 models; these samples use openai/gpt-6-luna.

curl

curl https://api.tokenspend.dev/v1/chat/completions \
  -H "Authorization: Bearer $TOKENSPEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"hello"}]}'

Install tokenspend from PyPI.

Python

import os
from tokenspend import Client

client = Client(api_key=os.environ["TOKENSPEND_API_KEY"])
print(client.chat.completions.create(
    model="openai/gpt-6-luna",
    messages=[{"role": "user", "content": "hello"}],
))

Install @tokenspend/sdk from npm.

TypeScript

import { TokenSpend } from "@tokenspend/sdk";

const client = new TokenSpend({
  apiKey: process.env.TOKENSPEND_API_KEY,
  baseURL: "https://api.tokenspend.dev/v1",
});

const res = await client.chat.completions.create({
  model: "openai/gpt-6-luna",
  messages: [{ role: "user", content: "hello" }],
});
console.log(res.choices[0].message.content);

Read the receipt

Each turn writes a receipt and route proof. The native body is unchanged; headers carry x-tokenspend-request-id, canonical model, revision, and registry version. Open the receipt for protocol, attempts, tokens, and list-price cost. The serving host is never part of the proof.

Headers

x-tokenspend-request-id: req_01k2h4
x-tokenspend-model: openai/gpt-6-luna
x-tokenspend-registry: 12
protocol: chat.completions
attempts: 1
input_tokens: 12
output_tokens: 48

Data handling

TokenSpend does not store prompts or responses. It does not currently offer provider ZDR; provider retention is separate.

Start routing

Connect a provider key, create a rail key, and point your tools at the rail.

Get started