Paying for the model

Every answer costs a little: providers charge for the AI model by the word. Your server pays one of three ways. provider.mode in config.yml picks between the first two.

#Your own key (`byok`)

Bring a key from OpenRouter or any other OpenAI-compatible API, and you pay the provider directly.

Fill in provider in plugins/Allay/config.yml:

provider:
  mode: byok
  byok:
    base_url: "https://openrouter.ai/api/v1"   # any OpenAI-compatible API
    api_key: "sk-or-v1-…"
    model: ""             # empty: the backend's default; it must be able to call tools
    search_model: ""      # empty: no web search; on OpenRouter, say, "perplexity/sonar"

Run /allay reload.
Run /allay status. It shows the API, the models, and the key with all but its ends hidden.

Allay looks into the game through tools, so a model that can't call them won't work. When a question fails, the note under it tells an operator what to change.

On allay.chat your own key costs nothing extra, up to 20 questions a minute and 2000 a day per server. Since 6.0 allay.chat still wants to know which server asks: on the first question Allay gets a free license as the server's identity and keeps it in license.key. It pays for nothing, and /allay status shows it. A key from before 5.0 in http.custom_headers (X-OpenRouter-Token) keeps working as your own OpenRouter key.

#A subscription (`hosted`, the default)

The backend answers on its own key and models, and you pay in Telegram Stars.

Run /allay link. The plugin gets a license, saves it in plugins/Allay/license.key, and shows a [Pay in Telegram] button; the console gets the plain link. The link works once and for 24 hours.
Pick a plan in the bot and pay with Stars:

Plan Stars Period

Week 150 ⭐ 7 days

Month 500 ⭐ 30 days, renews by itself

Year 10 000 ⭐ 365 days, the limit refills every 30 days
Run /allay status. It shows the plan, the date it's paid until, and a bar of how much of this period's limit is used.

Plan	Stars	Period
Week	150 ⭐	7 days
Month	500 ⭐	30 days, renews by itself
Year	10 000 ⭐	365 days, the limit refills every 30 days

Each plan has a usage limit per period. Allay checks the subscription every 5 minutes and tells operators online:

when a payment comes in;
when the limit passes 80% and 100%;
three days before a subscription that doesn't renew runs out, with a [Renew] button.

When the subscription lapses, players get a short, friendly note instead of an answer, and operators also get a link to pay. To pay again, run /allay link: it keeps the same license.

⚠️ Keep license.key to yourself. Whoever has it uses your subscription. Back it up with the server, but don't share it or commit it to a public repository. It never goes into the log, and config.yml doesn't hold it, so you can share your config when asking for help.

#Your own backend

An Allay Server started with SELFHOSTED=1 has no billing: it answers every plugin that sends its PLUGIN_TOKEN on its own key. Point server.url at it and put the token in server.token, as Installation shows, and there's nothing to pay or link. /allay status says so.

#Limits per player

Whoever pays, you can cap what Allay spends.

Turn the quota on and set a monthly budget:

quota:
  enabled: true
  monthly_usd: 20.0
  daily: true          # the budget opens day by day: by the 10th, a third of it
  tiers:
    default: 1          # everyone
    vip: 3              # players with allay.quota.vip weigh three times as much

Give tiers with your permission plugin: allay.quota.<tier>, with any tier names you like.

Optionally give a tier its own model:

models:
  vip: "anthropic/claude-sonnet-5.5"   # players with allay.model.vip get this model

Run /allay reload.

#How the split works

Nobody books money they don't use. A player's limit is what's open of the budget so far, times their weight, over the weights of everyone who asked this month:

a VIP alone may use all of it;
with one regular player around, it's 75% and 25%;
a third player makes it 60%, 20%, and 20%.

There's no guarantee, only a fair split. A player with several tiers gets the biggest weight, and operators get the biggest there is. Whoever reaches their limit hears when more comes: tomorrow with daily, else next month. Spending lives in plugins/Allay/quota.json.

A weight that isn't a number above 0 makes the config wrong. Allay then answers nobody, tells admins what's wrong when they join, and asks players to talk to an admin.

A model by tier replaces provider.byok.model. A self-hosted backend honors it too, on its own key. With several model tiers, the first one in the list that the player has wins.

Next: First steps

#Your own key (byok)

#A subscription (hosted, the default)

#Your own backend

#Limits per player

#How the split works

#Your own key (`byok`)

#A subscription (`hosted`, the default)