Skip to content

4 Uncensored LLM model added, currently available for only pay-as-you-go users.See Models

Plans, usage and wallet

How subscription plans, plan usage, usage windows and the pay-as-you-go wallet work on Tokens, what happens when a window or your balance runs out, and how renewal, cancellation and coupons work.

Last updated 17 Nov 2026

On this page

Tokens has two ways to pay for usage: a subscription plan that includes an amount of usage in US dollars, and a prepaid wallet for pay-as-you-go. This page explains how plans and the wallet fit together, and exactly what happens when something runs out. Current plans and prices are on pricing.

Subscription plans vs pay-as-you-go wallet#

PlanWallet
What you buyA weekly, monthly or yearly amount of usage, in USDA USD balance
Good forSteady daily use, predictable costOccasional use, or extra on top of a plan
LimitsPlan's usage windows, rate limit and concurrencyRate limit and concurrency
ModelsThe models included in the planEvery model sold pay-as-you-go
RenewalOne payment per period, renewed by youTop up when you want

You can have both. With a plan, usage is paid from the plan's credits first, unless you choose otherwise (next section).

Choose what pays: plan, Auto or wallet#

With a plan and a wallet, you choose what pays for requests under What pays for requests on the dashboard or the billing page. The change applies from your next request.

SettingWhat pays
Plan credits (default)Your plan. Requests pause while a 5-hour, weekly or monthly limit is reached. When the credits run out, the wallet pays only if your plan has pay-as-you-go fallback.
AutoYour plan first. When a 5-hour, weekly or monthly limit is reached, the credits run out, or a model's allowance is used up, your wallet pays. Once the limit resets (or new credits arrive) your plan pays again.
Wallet onlyYour wallet pays every request. Plan credits and limits aren't used and stay for later.
  • Requests paid from the wallet have no 5-hour, weekly or monthly limits, and don't count toward them. Per-minute and concurrency limits still apply to every request, and so do key and team spend caps.
  • Wallet money is charged at the full catalog price. Plan deals apply only to plan credits.
  • Free models stay free. A model your plan makes free is never charged to the wallet, whatever you choose.
  • If the wallet can't pay: on Auto, requests wait for the limit to reset as they would on Plan credits. On Wallet only, they fail with 402 insufficient_credits until you top up or switch back.
  • On a team, the setting applies to the whole team. Owners, admins and billing members can change it.

Each response says what paid for it in the x-tokens-paid-by header (plan, wallet or free). When the wallet paid on a plan account, x-tokens-wallet-reason says why: limit (a usage limit was reached), credits (plan credits ran out), model_limit (the model's allowance was used up) or manual (Wallet only).

How plan usage works#

A plan includes an amount of usage in US dollars for each billing period, for example $20 a month. There is no separate credit unit: the dashboard calls what is left of that amount your plan credits, and shows it in dollars. Every request costs what the model's catalog price says for the tokens it used (input, output and cache-read tokens), and that cost is deducted from the plan's usage when the response finishes. Prices per model are on /models.

Plan credits belong to the billing period they were bought for.

Per-model allowances, free models and deals#

Some plans give particular models their own allowance, make some models free, or put a model on a deal. The plan's page on pricing lists them, for example "$10 on DeepSeek V4.1 Flash", "10M tokens of Claude Sonnet 5.5" or "Free on Ling 3.1 Flash".

  • An allowance is a cap inside your plan's usage, not extra on top. Using a model draws from the plan's credits and from that model's allowance at the same time. With $10 of plan usage and a $10 allowance on DeepSeek V4.1 Flash, spending $5 on DeepSeek leaves $5 of allowance for DeepSeek and $5 of plan usage for every model. If you then spend the other $5 on another model, the plan is empty and DeepSeek stops too, even though its own allowance still shows $5.
  • A model without an allowance uses the plan's credits only, at the price in the model catalog.
  • A free model costs nothing. It doesn't use your credits or any allowance, and it keeps working after your plan's credits run out.
  • A token allowance gives a model its own number of tokens for the billing period, separate from the plan's credits. Every token counts: input, output, and cached input read or written. Requests it covers cost nothing from your credits or your wallet, and some plans are made of token allowances only. A request that starts before the allowance is used up is allowed to finish, even if it ends slightly over; the gateway lowers that request's maximum output to the tokens left.
  • A deal lowers the price of that model, so the same credits go further. Wallet money is never discounted: if a request is paid from your wallet, it costs the full catalog price.
  • Allowances reset with your billing period, the same day your plan's credits do. Your dashboard's Usage page shows how much of each allowance you have used and when it resets, and you get an email when a model reaches 80% and 100% of a dollar allowance.

When one model's allowance is used up, requests to that model return 429 model_limit_reached until the reset, and your other models keep working. On a plan with pay-as-you-go fallback, or with What pays set to Auto, requests to that model are paid from your wallet instead, at the full price.

json
{
  "error": {
    "message": "You've used your $10.00 allowance for DeepSeek V4.1 Flash this billing period. It resets on 4 Nov 2026. Other models on your plan still work. See your plan: https://tokens.bd/dashboard/billing",
    "type": "rate_limit_error",
    "code": "model_limit_reached"
  }
}

Usage windows: 5-hour, weekly and monthly#

Some plans also spread the allowance over time with usage windows, so that a single heavy day can't burn a month's credits. A plan can have any of these:

WindowHow it resets
5-hour sessionStarts with your first request after the previous session ended, and resets exactly 5 hours later
WeeklyEvery Monday at 00:00 UTC
MonthlyAt the end of your billing period; on a yearly plan, every month from the day the period started

A window is measured either in credits or in number of requests, depending on the plan. You can see each window's use and reset time in the dashboard, with node tokens.mjs usage, or with GET /v1/tokens/usage. See usage, limits and alerts.

What happens when a window or your balance runs out#

A usage window is used up: 429 window_exhausted#

json
{
  "error": {
    "message": "Your plan's session_5h limit has been reached. Resets in 5400s. Upgrade your plan or wait for the window to reset: https://tokens.bd/dashboard/billing",
    "type": "rate_limit_error",
    "code": "window_exhausted",
    "param": null,
    "request_id": "..."
  }
}

The response has a Retry-After header with the number of seconds until the window resets. On the default Plan credits setting, wallet balance doesn't bypass a plan window: requests wait for the reset. To keep going on your wallet instead, set what pays to Auto. Don't retry in a tight loop; Retry-After can be hours.

Plan credits run out#

Each plan is set either to stop when its credits run out, or to continue from your wallet (pay-as-you-go fallback). On a fallback plan, or with what pays set to Auto, requests carry on as long as the wallet has money. Otherwise they fail with 402 insufficient_credits until the next period or a new plan. If you're not sure how your plan behaves, ask support.

A request that starts while you still have credits is allowed to finish. If it costs more than the credits you had left, your wallet pays the rest when it has enough for all of it, at the same price, and the response's x-tokens-paid-by header says plan. Only when the wallet can't pay the rest is it recorded as an unpaid amount (402 outstanding_debt on the next request until it is paid from new credits or a top-up). New requests still stop when the credits are used up, as above.

The wallet is low or empty#

  • Low balance: if your balance can't cover the max_tokens you asked for, Tokens may lower max_tokens to what the balance covers (never below 16). The answer comes back shorter, usually with finish_reason: "length". Top up before long agent sessions.
  • Empty: 402 insufficient_credits. All 402 messages link to /dashboard/billing.

Other billing errors#

HTTPCodeMeaning
402no_fundingNo active plan and no wallet balance
402outstanding_debtA previous request left an unpaid amount; top up to clear it
429model_limit_reachedThis model's allowance on your plan is used up; other models still work
403tier_permission_deniedYour plan doesn't include this model and the wallet has no balance to pay for it
403monthly_spend_cap_exceededThe key's own monthly cap, not your account; see API keys

The full list is in errors.

Top up the wallet#

Open /dashboard/billing and add funds. The minimum top-up is $5 if you pay in dollars and ৳500 if you pay in taka. The wallet is kept in USD; if you pay in taka, the amount is converted at the exchange rate locked when you start checkout. See paying in BDT. The Wallet page in the dashboard shows every credit and debit in a ledger.

A low-balance email alert is on by default and fires when the wallet drops below $5. You can switch it off under Notifications in the dashboard.

Auto top-up#

So an agent doesn't stop overnight when the wallet runs out, you can have the wallet topped up automatically from a card. It is off until you turn it on, and only where Tokens offers it (the card appears on the Wallet page when it does).

  1. On the Wallet page, under Auto top-up, choose Save a card. The card is saved by Stripe on Stripe's own page; Tokens keeps only the card brand, the last four digits and the expiry date.
  2. Choose three amounts: the balance to top up below (for example $5), how much to add each time (for example $20), and a monthly cap, the most that may be charged in a calendar month (UTC). The page shows the smallest and largest amounts allowed.
  3. Tick the box that agrees to the charges, and choose Turn on auto top-up.

What Tokens promises:

  • Never more than your monthly cap in a calendar month, and never more than once an hour, however fast the wallet drains.
  • A receipt by email for every charge, with the card, the month so far against your cap, and a link to change or turn off auto top-up.
  • Money is added only when the bank confirms the payment, the same way as a card top-up you make yourself. The check runs every few minutes, so a top-up arrives a few minutes after the balance drops, not during a request.
  • If a charge fails (declined, expired card, or your bank asks you to confirm), nothing is charged and you get an email. After 3 failed charges in a row, auto top-up turns itself off until you save a card again or turn it back on.
  • Turn it off, change the amounts or remove the card at any time on the Wallet page. Removing the card turns auto top-up off.

bKash and Nagad can't be charged automatically, so there is no automatic charge in taka. Instead, when Tokens offers it, the low-balance email and Telegram alert carry a Pay ৳… with bKash / Nagad link. It opens the wallet top-up already filled in with your amount in taka; you choose bKash, Nagad or another method and confirm the payment as usual. Set the amount under Auto top-up on the Wallet page (the default is ৳1,000).

Renewal and cancellation#

  • Renewal is a one-time payment per period. Nothing is charged automatically. Before the period ends you get a renewal reminder (if that notification is on), and you renew from /dashboard/billing.
  • A period you paid for in advance waits for you. When your current period ends, the next one you already bought starts with your first request or dashboard visit after that, not while you are away. If you are back within minutes, it starts within minutes.
  • A yearly plan is one payment for 365 days. Its credits and per-model allowances are for the whole year, and its 5-hour, weekly and monthly windows still reset on their own schedule inside it. Its price card also shows what it comes to per month.
  • Cancelling stops the plan at the end of the current period. You keep the plan and its remaining credits until then. Cancelling the free plan is final too: it is not given back when you next sign in. Buying a plan later brings it back when that plan ends.
  • Upgrading is buying a plan that costs more per day; compare them on pricing. It starts at once with a fresh period and the new plan's full credits, and the plan credits you had left are added to them, so none of the credit you paid for is lost. The days left on the old plan are not refunded. A plan that costs the same or less per day starts when your current period ends.
  • A refunded plan payment affects only the period it paid for. A renewal that has not started yet is removed and your current period carries on. A refund of the period you are in ends it: the next period you already paid for starts at once, or, with none, you move to the free plan. A partial refund keeps the plan and takes the same share of that period's credits.

Coupons and referrals#

If you have a coupon code, enter it at plan checkout. The discount is shown before you pay.

The referral program gives you a link in the form /r/<code> under Referrals in the dashboard. When people you refer pay, a commission is credited to your wallet. Current terms are shown on the Referrals page.

Was this page helpful?

Still stuck? Open a support ticket

Need help configuring your agent?

Test your connection with the connection tester, or create an API key.