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/v1curl 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.
Errors
Errors use the OpenAI error shape: { "error": { "message", "type", "code" } }.
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.