Docs. One endpoint, one key.

TOKENS is an OpenAI-compatible API. Holders of $TOKENS get a key, and each key can spend its wallet’s share of the daily pool. If your tool or code can talk to OpenAI, it can talk to TOKENS.

Quick start

1. Hold at least 100,000 $TOKENS. 2. Open Your key, connect the wallet and sign the message. 3. Use the key with this base URL:

https://www.holdtokens.fun/v1
curl https://www.holdtokens.fun/v1/chat/completions \
  -H "Authorization: Bearer tok_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-5.5",
    "messages": [{"role": "user", "content": "gm"}]
  }'

A key belongs to one wallet. Signing again issues a new key and switches the old one off, so that is also how you rotate a leaked key.

Your allowance

Every day (UTC) a wallet can spend pool × balance ÷ supply dollars. The pool is the credit balance bought with the coin’s fees, plus whatever holders have already used that day, so your cap does not shrink as others spend. Credit nobody uses stays in the pool for the next day.

Before a request runs, its worst-case cost (the prompt plus max_tokens of output) is held against your day. If your remaining allowance cannot cover the full max_tokens, the reply is capped to what you can afford. When it finishes, the hold is replaced by the real cost.

Your balance is read from the chain and remembered for one minute. If the wallet falls under 100,000 $TOKENS the key pauses (403) until it is back above the minimum.

Chat completions

POST /v1/chat/completions takes the OpenAI request shape. These fields are passed on: messages, temperature, top_p, stop, stream, tools, tool_choice, response_format, seed, frequency_penalty, presence_penalty, reasoning. max_tokens defaults to 1,024. Other fields are dropped.

Messages are text only for now. With stream: true you get server-sent events, and the last event carries usage with the token counts and the cost in dollars.

from openai import OpenAI

client = OpenAI(base_url="https://www.holdtokens.fun/v1", api_key="tok_...")

stream = client.chat.completions.create(
    model="openai/gpt-6-luna",
    messages=[{"role": "user", "content": "Explain slippage in one line."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Models

GET /v1/models needs no key. It lists every model that is on, with its price per token.

anthropic/claude-haiku-5.5$0.10 in · $0.50 out / 1M
anthropic/claude-sonnet-5.5$2.00 in · $10.00 out / 1M
anthropic/claude-opus-5.5$4.00 in · $20.00 out / 1M
anthropic/claude-fable-5.2$8.00 in · $40.00 out / 1M
openai/gpt-6-luna$0.10 in · $0.50 out / 1M
openai/gpt-6.1-terra$1.00 in · $5.00 out / 1M
openai/gpt-6.1-sol$2.00 in · $10.00 out / 1M
google/gemini-3.8-flash$0.83 in · $4.13 out / 1M
google/gemini-4-hydrogen$1.50 in · $7.50 out / 1M
x-ai/grok-4.7$2.00 in · $6.00 out / 1M
deepseek/deepseek-v4.1-flash$0.30 in · $1.20 out / 1M

Errors

Errors use the OpenAI error shape: { "error": { "message", "type", "code" } }.

401invalid_api_keyThe key is unknown or was replaced by a newer one.
403key_pausedThe wallet holds less than 100,000 $TOKENS.
402allowance_exhaustedToday’s allowance is used. It refills at 00:00 UTC, or sooner when the pool is topped up.
402pool_emptyThe pool itself is empty until fees refill it.
400model_not_foundThe model is not in the list.
400bad_messagesMessages are missing or contain non-text content.
502upstream_downThe model provider did not answer. Nothing was charged.

The public meter

GET /api/stats returns the pool, today’s usage, all-time totals and the latest requests. GET /api/me?wallet=… returns one wallet’s balance, cap and spend for the day. Both are open, because everything in them is already public on chain or on the meter.

What is stored

For each request: the wallet, the model, the token count, the cost and the time. Keys are stored as hashes. Prompts and replies are passed to the model and back and are not stored by TOKENS. Requests are served by the model makers through a gateway, under their own terms.