Skip to content

Plugin protocol billing

Pavel Erokhin edited this page Nov 9, 2026 · 2 revisions

Part of the Plugin protocol: how a server pays for the model, its license, and how the plugin sets up the admin panel's first account. Who pays for the model explains the same for server owners.

Providers and billing

Since 5.0. A server pays for the model one of two ways, and the plugin picks with provider.mode in its config.

Bring your own key (BYOK)

The request carries the server's own key in X-Provider-Key and the rest in the body:

"provider": {
  "base_url": "https://openrouter.ai/api/v1", // any OpenAI-compatible API; empty means OpenRouter
  "model": "openai/gpt-6-luna",              // empty means the backend's default model
  "search_model": "perplexity/sonar"         // empty: the run gets no search_web
}

The backend uses the key for this run only. It never stores it, never logs it, and blanks it out of every error message it passes on. OpenRouter gets OpenRouter's own provider, and any other base_url gets a plain OpenAI-compatible client. On a backend with billing on, base_url must be https:// and resolve to a public address.

The model must call tools. For OpenRouter the backend checks the model's supported_parameters before the run. For other APIs it reads the provider's refusal. Errors before the stream starts:

Code Status Meaning
PROVIDER_AUTH_FAILED 401 The provider refused the key
MODEL_NOT_FOUND 400 The provider doesn't know this model
MODEL_NO_TOOLS 400 The model can't call tools, and Allay needs that
PROVIDER_URL_REJECTED 400 base_url isn't https, or points into a private network
RATE_LIMITED 429 Too many questions from this server. retry_after (seconds) says when to come back

The same codes can arrive as an error event when the provider only fails mid-run. On a backend with billing on, BYOK is free and needs a license as the server's identity (since 6.0). It's limited per license: 20 questions a minute, 2000 a day, 4 at once, and all BYOK servers together take at most BYOK_ACTIVE_RUNS (100) slots, so paying servers always have room. A blocked license can't ask with its own key either. Every request to the provider goes through a guard that checks the address again and refuses redirects.

X-OpenRouter-Token without a provider block is BYOK on OpenRouter with the backend's default models.

Subscription (hosted)

Without a key, the request runs on the backend's own key and models. The plugin sends Authorization: Bearer <license>, where the license is <license id>.<secret> from POST /api/v2/license. The backend ignores everything the plugin says about the model.

Code Status Meaning
LICENSE_REQUIRED, LICENSE_INVALID 401 See Who is asking
SUBSCRIPTION_INACTIVE 402 Nothing paid for now, the period ended, or the license is blocked
QUOTA_EXCEEDED 402 This period's limit is spent. resets_at (ISO-8601) says when it refills, absent when only a new payment helps
PLAYER_BLOCKED 403 Since 6.2: the backend's operators blocked this player on this server (also from /api/v1/ask and /api/v1/askx). Plugins before 6.2 show it as a general error
SOLO_PLAYER_TAKEN 403 Since 6.12: a Solo license answers the first player who asked on it, and this is another one (also from /api/v1/ask and /api/v1/askx). The payer hands it to another player in the bot, an admin in the panel
CONSENT_REQUIRED 403 Since 6.9, on a hosted backend: the player has no agreement in force on this server, so the backend runs, traces, and keeps nothing (also from /api/v1/ask and /api/v1/askx, and POST /memories, POST /deaths, PUT /state). console and requests without a player pass. The plugin shows the notice again

Before a stream these come as { "error": { "code", "message", "resets_at"?, "retry_after"? } }.

The limit is a budget in US dollars: what the server's questions really cost, counting the model, web search, and the session summaries. Each run is charged when it ends, so one run can overshoot a little.

A backend with billing off (SELFHOSTED=1, as on a server's own backend) never asks for a license, only for its PLUGIN_TOKEN: it serves its plugins on its own key, and BYOK still works without limits. Since 5.5, such a backend honors provider.model from a request without a key: the run (and its session summary) uses that model on the backend's own key, so the plugin can give each player tier its own model. base_url and search_model are ignored there, and search stays the backend's own. With billing on, a request without a key never picks the model.

License endpoints

Request Answer
POST /api/v2/license without Authorization 200 { "license": "<id>.<secret>", "license_id", "claim_code", "pay_url": "https://t.me/<bot>?start=<claim code>", "claim_expires_at" }: a new license. The plugin keeps license in plugins/Allay/license.key and shows pay_url. Free, and limited to 10 an hour per client address (an IPv6 /64 counts as one) and 500 an hour in all
POST /api/v2/license with Authorization: Bearer <license> The same shape without license: a fresh claim code for the existing license
GET /api/v2/license with Authorization 200 with the status below
any of them with billing off 200 { "billing": false }

Both POSTs take an optional body { "name": "…", "loader"?, "side"? }: name (≤ 64 chars) is the server's name as the bot shows it to the payer, and the plugin sends its MOTD without formatting codes. Since 6.12, a new license whose side is integrated or client is a Solo license while the backend sells Solo plans (SOLO_PLANS). Every other is a server's. A Solo license serves one player: the first who asks on it takes it, by pseudonym, and anyone else gets SOLO_PLAYER_TAKEN.

The status:

{
  "billing": true,
  "license_id": "k3f9a2…",
  "linked": true,                         // a Telegram account claimed it
  "active": true,
  "kind": "server",                       // since 6.12: server, or solo for one player
  "bound": true,                          // solo only: a player has it
  "plan": "month",                        // week | month | year | solo_week | solo_month | solo_year; null before the first payment
  "paid_until": "2026-11-14T10:00:00Z",   // null before the first payment
  "renews": true,                         // a Telegram Stars subscription renews it by itself
  "quota": { "used_percent": 62, "resets_at": "2026-11-14T10:00:00Z" },
  "last_payment_at": "2026-10-14T10:00:00Z"
}

quota.resets_at is when the current budget ends: the period's end, or for a year the next monthly refill. A claim code works once and for 24 hours. The plugin polls the status every few minutes, tells online operators when last_payment_at changes, when used_percent passes 80 and 100, and three days before paid_until.

Paying

https://t.me/<bot>?start=<claim code> opens the backend's Telegram bot. /start <claim code> ties the license to that Telegram account and shows the plans. Payment goes in Telegram Stars.

Plan Stars Period Budget
week 150 7 days $0.75
month 500 30 days, renews by itself as a Stars subscription $3.00
year 10 000 365 days $6.00 a month, refilled every 30 days
infinity not sold 366 days $1000 for the whole period (PLAN_INFINITY_BUDGET). Since 6.9 an owner grants it in the admin panel

A payment while a period runs adds its budget at once and moves paid_until further.

Since 6.12 a Solo license buys Solo plans instead, and a server's license never does. The bot sells them only while SOLO_PLANS is on (off until the mods ship):

Plan Stars Period Budget
solo_week 50 7 days $0.25
solo_month 150 30 days, renews by itself as a Stars subscription $1.00
solo_year 3000 365 days $2.00 a month, refilled every 30 days

In /status the payer hands a Solo license to another player, once every SOLO_RELEASE_DAYS (30), and an admin may in the panel any time.

Admin panel setup

Since server 5.7 and plugin 5.9. The backend has a web admin panel at <PUBLIC_URL>/admin. On a self-hosted backend (SELFHOSTED=1), an operator creates its first account from the game with /allay init, which calls the following. Since 6.0 it wants the backend's PLUGIN_TOKEN (401 without it): a recovery code resets any account's password, so only the backend's own plugin may ask for one.

Request Answer
POST /api/v2/admin/init, no body 200 { "url": "<PUBLIC_URL>/admin/setup?code=<code>", "expires_at", "mode": "setup" } while the panel has no admin. The code works once and for 30 minutes. A new call replaces a pending one
the same once an account exists (since server 5.10) 200 { "url": "<PUBLIC_URL>/admin/recover?code=<code>", "expires_at", "mode": "recover" }: a recovery link that sets a new password for any account the panel keeps. Same rules: once, 30 minutes, a new call replaces a pending one. Setup and recovery codes never stand in for each other
the same when the only admin is defined in the environment, or on servers before 5.10 once an admin exists 409 { "error": { "code": "ADMIN_EXISTS", … }, "url": "<PUBLIC_URL>/admin" }
the same on a backend with billing on 404 { "error": { "code": "NOT_SELFHOSTED", … } } for a license holder, 401 for anyone else: its first admin comes from a code in its own log

The plugin shows the link only to whoever ran the command, as a clickable chat line, and never logs it. From the console it prints it to the console. It reads mode to say which link it is, and an answer without mode is a setup link. Older backends answer 404 without that code: the plugin then says the backend has no panel.

The recovery page posts { code, username, password } to the panel's POST /api/admin/recover. It sets the new password, ends every session of that account, writes recover to the audit log, and signs in. A wrong or spent code answers 400 BAD_CODE, and five of them from one address lock recovery for 15 minutes. The environment's admin (ENV_ADMIN) and an unknown name (NO_ACCOUNT) keep the code alive.

Next: Architecture

Clone this wiki locally