Dokumentation

Drei Wege, ein Ziel: jeder Aufruf gehört zu einem Agenten und einem Lauf. Schlüssel und Adressen finden Sie nach der Registrierung im Cockpit unter „Erststart".

Weg A · Proxy (empfohlen)

Basis-URL tauschen, Kopfzeilen setzen — fertig. Ihr Anbieterschlüssel bleibt Ihr Schlüssel und wird nur durchgereicht.

from anthropic import Anthropic
client = Anthropic(
    base_url="https://tokenwacht.de/anthropic",
    api_key=os.environ["ANTHROPIC_API_KEY"],
    default_headers={"X-TW-Key": "tw_live_…", "X-TW-Agent": "nils-icp-research",
                     "X-TW-Run": run_id, "X-TW-Kunde": "kunde-4711"},
)

from openai import OpenAI
client = OpenAI(base_url="https://tokenwacht.de/openai/v1",
                default_headers={"X-TW-Key": "tw_live_…", "X-TW-Agent": "…"})

Kopfzeilen

Kopfzeile	Pflicht	Bedeutung
X-TW-Key	ja	Ihr Tokenwacht-Schlüssel. Ohne ihn wird nichts weitergereicht.
X-TW-Agent	empfohlen	Der Agent als dauerhafte Einheit, z. B. nils-icp-research.
X-TW-Run	empfohlen	Lauf-Kennung (UUID oder Text). Fehlt sie, bildet Tokenwacht Läufe automatisch (15 Minuten Pause = neuer Lauf).
X-TW-Step, X-TW-Kunde, X-TW-Funktion, X-TW-Benutzer	optional	Schritt, Endkunde (Weiterbelastung), Funktion, Benutzer.

Ablehnung (HTTP 402)

Greift eine Regel mit Stufe „stoppen", antwortet der Proxy statt des Anbieters — maschinenlesbar, damit Ihr Agent geordnet enden kann:

{"fehler": "tokenwacht_budget_ueberschritten", "regel": "lauf_budget", "grenze": "2.5000",
 "verbraucht_eur": "2.5400", "schritte": 41, "lauf_id": "…", "hinweis": "…", "cockpit_url": "…"}

Weg C · Python-SDK

from tokenwacht_sdk import Wacht, BudgetUeberschritten
wacht = Wacht(schluessel="tw_live_…", agent="nils-icp-research", kunde="kunde-4711")
client = Anthropic(api_key=…, base_url=wacht.anthropic_url(), http_client=wacht.http_client())
with wacht.lauf("RL-0815") as lauf:
    try:
        client.messages.create(…)
        lauf.schritt("leadliste_erzeugen")
    except BudgetUeberschritten as b:
        print(b.hinweis, b.cockpit_url)

Weg D · Ingest-Schnittstelle

POST https://tokenwacht.de/v1/ereignisse
Authorization: Bearer tw_live_…
Idempotency-Key: <uuid>

{"ereignisse": [{"ereignis_id": "…", "zeitpunkt": "2026-09-05T10:00:00Z", "anbieter": "anthropic",
  "modell": "claude-sonnet-5", "agent": "nils-icp-research", "lauf_id": "…", "schritt_nr": 3,
  "eingabe_token": 1200, "ausgabe_token": 57, "cache_lese_token": 800, "cache_schreib_token": 0,
  "status": "erfolgreich", "prompt_fingerabdruck": "…16 hex…", "endkunde_ref": "kunde-4711"}]}

Bis 500 Ereignisse je Stapel, mehrfach sendbar ohne Doppelzählung. Unvollständige Ereignisse werden angenommen und als solche gekennzeichnet — Datenannahme scheitert nie.

Regeln und Stufen

Sechs Regeltypen: Lauf-Budget, Tagesbudget je Agent, Monatsbudget, Ratenbegrenzung, Modellsperre mit Zeitfenster, Schutzregel je Detektor. Jede Regel läuft zuerst im Schattenbetrieb: sie wird gemessen, greift aber nicht. Erst nach Sichtung schalten Sie sie scharf.

Selbstbetrieb

Dieselbe Docker-Compose-Datei wie der EU-Betrieb: Postgres 16 + TimescaleDB, Valkey, API, Worker. Anleitung im Repository.