TokenParty

---

Why TokenParty?

Save Money — Smart routing picks the cheapest provider for each model. Set monthly budgets per user. See exactly where every dollar goes.

Stay Simple — One endpoint for all providers. Send OpenAI-format requests to Claude, or Anthropic-format to GPT. Protocol translation is transparent.

Keep Control — Scoped API keys, provider-level access control, full request logging, and separate admin/user dashboards give the right view to the right person.

Zero Ops — Single Node.js process, embedded SQLite, no Redis, no Postgres, no Docker required. Just npx tokenparty and you're running.

┌─────────────┐       ┌──────────────┐       ┌──────────────────┐
│  Your Apps  │──────▶│  TokenParty  │──────▶│  OpenAI / Claude  │
│  (any SDK)  │◀──────│   Gateway    │◀──────│  / DeepSeek / ... │
└─────────────┘       └──────────────┘       └──────────────────┘
                            │
                      ┌─────┴─────┐
                      │ Dashboard │
                      └───────────┘

Quick Start

npx (zero install)

npx @tokenparty/tokenparty

npm global

npm install -g @tokenparty/tokenparty
tokenparty

Docker

# Create docker-compose.yaml, then:
docker compose up -d

services:
  tokenparty:
    image: nfqlt/node22
    entrypoint: sh -c "npm install -g @tokenparty/tokenparty && tokenparty"
    ports:
      - "3456:3456"
    volumes:
      - npm_global:/usr/local
      - ./tokenparty-data:/root/.tokenparty
    restart: unless-stopped

volumes:
  npm_global:

Open http://localhost:3456 — configure providers and tokens from the dashboard.

Use it

Point any OpenAI-compatible SDK at your gateway:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3456/v1",
    api_key="tp-***"
)

# Routes to the cheapest provider automatically
response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello!"}]
)

Or use the Anthropic SDK:

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:3456/anthropic",
    api_key="tp-***"
)

# GPT-4o through the Anthropic SDK — protocol converted transparently
message = client.messages.create(
    model="gpt-4o",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

Dashboard

Admin Portal — Overview with cost/usage charts, request inspector with full prompt/response detail, provider management with groups, user & budget management, settings.

User Portal — Personal cost dashboard, budget progress, cache hit rate, model-level breakdown, request history.

Agent Aware — Automatically detects Claude Code, OpenClaw, and other AI agents. Shows per-agent usage breakdown in the dashboard.

Features

Category	Feature
Routing	Cost-based smart routing across providers
Routing	Provider fallback & automatic retry
Routing	Multi-key load balancing (round-robin)
Routing	Model-level priority with ordered fallback chain
Protocol	OpenAI ↔ Anthropic bidirectional conversion
Protocol	Full SSE streaming with protocol translation
Protocol	OpenAI Chat, Responses, and Models API support
Cost	Per-model pricing configuration (input/output/cache)
Cost	Monthly budget enforcement per user
Cost	Cost analytics by user, provider, model, and tag
Cost	Cache hit rate tracking
Cost	USD/CNY dual currency support
Access	Scoped API keys with provider-level access control
Access	Provider groups for bulk access rules
Access	Usage quotas per token
Access	Admin authentication
Observability	Real-time usage dashboard with charts
Observability	Full request/response JSONL audit logs
Observability	Route trace — see exactly how each request was routed
Observability	Custom tags via x-tkparty-tags header
Observability	Request filtering by user, provider, model, status, tags
Observability	AI agent detection (Claude Code, OpenClaw)
Operations	Hot-reload config (no restart needed)

Configuration

providers:
  - id: anthropic-main
    type: anthropic
    name: "Anthropic"
    apiKey: ${ANTHROPIC_API_KEY}
    baseUrl: https://api.anthropic.com
    group: production
    models:
      - id: claude-sonnet-4-20250514
        inputPrice: 3        # $ per 1M tokens
        outputPrice: 15
        cacheReadPrice: 0.3
      - claude-opus-4-20250514

  - id: openai-main
    type: openai
    name: "OpenAI"
    apiKey: ${OPENAI_API_KEY}
    baseUrl: https://api.openai.com/v1
    group: production
    models:
      - gpt-4o
      - gpt-4o-mini

tokens:
  - key: tp-team-alice
    name: "Alice"
    allowedProviders: ["group:production"]
    monthlyBudget: 100      # USD — enforced by the proxy
    enabled: true

  - key: tp-team-bob
    name: "Bob"
    allowedProviders: [openai-main]
    monthlyBudget: 50
    enabled: true

Unconfigured model prices are treated as free and routed with highest priority. Environment variables in ${VAR} format are resolved at startup.

Architecture

TokenParty/
├── packages/
│   ├── proxy/          # Hono reverse proxy (TypeScript)
│   │   └── src/
│   │       ├── adapters/       # OpenAI ↔ Anthropic translators
│   │       ├── proxy/          # Auth, routing, forwarding
│   │       ├── metrics/        # Usage collection → SQLite
│   │       ├── routes/         # Admin & user API handlers
│   │       ├── tags/           # Agent detection & tag extraction
│   │       └── store/          # Database & log writer
│   └── dashboard/      # React + Vite + Tailwind + Recharts
│       └── src/
│           ├── layouts/        # Admin & User layouts
│           └── pages/          # Overview, Requests, Providers, Users, Settings

Component	Tech	Role
Gateway	Hono + Node.js	Reverse proxy with streaming SSE
Storage	better-sqlite3 (WAL)	Usage aggregation & request index
Logs	JSONL files	Full request/response audit trail
Dashboard	React 19 + Vite 6	Admin & user monitoring UI
Config	YAML + chokidar	Hot-reloadable setup

How It Works

1. Add providers — Configure your OpenAI, Anthropic, DeepSeek, etc. API keys in the dashboard or YAML
2. Create tokens — Generate scoped API keys for your team with budgets and provider access rules
3. Point your apps — Any OpenAI or Anthropic SDK, just change the base_url
4. Observe — Watch costs, usage, and full request traces in real-time

Roadmap

• npm package & Docker deployment
• Multi-provider support with load balancing
• OpenAI ↔ Anthropic protocol translation
• Full SSE streaming with protocol conversion
• Cost-based smart routing
• Per-user monthly budget enforcement
• Separate admin & user portals
• Multi-account quick switching
• Real-time cost & usage dashboard
• Request inspector with full audit trail
• Custom tags & filtering
• Provider groups & access control
• Provider fallback / retry
• Log storage management
• Configurable log retention (1 week / 1 month / 2 months) + rolling daily cleanup; Overview aggregates preserved
• AI agent detection & per-agent detail panel (Claude Code, OpenClaw)
• Model-level priority with ordered fallback chain across providers
• Route trace — visual routing diagram for each request
• Upstream model auto-discovery
• Connection pooling (keep-alive HTTP agents) — prevents TIME_WAIT port exhaustion
• Provider config validation (rejects invalid baseUrl etc. at save time)
• Dashboard copy-as-cURL on request route trace
• Shareable request URLs (filters, pagination, and detail id in URL)

See the full roadmap and open issues for what's next.

Comparison

	TokenParty	LiteLLM	One API	Portkey
Self-hosted	✅	✅	✅	❌ (SaaS)
Language	TypeScript / Node.js	Python	Go	—
Zero dependencies	✅ (SQLite, no Redis/PG)	❌ (Postgres/Redis)	✅	—
Protocol translation	OpenAI ↔ Anthropic	OpenAI only	OpenAI only	OpenAI only
Built-in dashboard	✅ (React)	❌ (separate)	✅ (basic)	✅
Per-user budgets	✅	❌	✅ (basic)	✅
Agent detection	✅	❌	❌	❌

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup and guidelines.

License

MIT © 2026 Zhou Zhengchang

---