Stolo API token charges
Stolo API token charges apply only to historical data from the analysis endpoints, the ones that return market data. Anything for the current trading day is free. Historical requests are paid for in Stolo Tokens, the same balance you use elsewhere on Stolo, taken from the account that owns your API app, and a paid request is free to repeat for 24 hours. Authenticating and trading cost nothing.
This page covers what each endpoint costs, how repeats and historical candles are priced, when a call is free or refunded, and how to estimate what a script will use in a day.
What each endpoint costs
Only historical data is charged. The current trading day is free on every endpoint: that's today on a trading day, and the last trading day on weekends and market holidays (on a Saturday, Friday's data is free). Any earlier date is historical.
| Endpoint | Current trading day | A past date |
|---|---|---|
POST /authenticate | Free | Free |
GET /analysis/symbol/info | Free | 1 token per request |
GET /analysis/option-chain | Free, including live data | 1 token per request |
GET /analysis/candles/intraday | Free once today's session is served (after 3:40 PM) | Before 3:40 PM it returns the previous session: 1 token per symbol, like historical candles |
GET /analysis/candles/historical | Free | 1 token per symbol per trading day returned |
/trade/* (place, cancel, positions, orders, margins) | Free | Free |
Every charge is free to repeat for 24 hours. See repeat requests.
A few terms used on this page:
| Term | What it means |
|---|---|
| Stolo Tokens | Stolo's usage currency. The same balance pays for API calls and other paid actions on Stolo. |
| Current trading day | Today on a trading day; the last trading day on weekends and market holidays. Always free. |
| Charge | Tokens taken from your balance when a call runs. |
| Refund | A charge given back automatically because the call failed. |
| Candle day | One symbol's candles for one trading day, the unit historical candles are priced in. |
Repeat requests are free for 24 hours
When a past-date request is charged, the same request costs nothing for the next 24 hours. "The same request" means the same data:
| Endpoint | Same request when these match |
|---|---|
| Symbol info | Symbol and date |
| Option chain | Symbol, date, and expiry |
| Candles (intraday and historical) | Symbol and day, in any range and at any resolution |
Defaults count as the values they resolve to, so leaving expiry out and passing the
nearest expiry yourself are the same request. The 24 hours run from the charge, and free
repeats don't extend them. After 24 hours the next request is charged again, and a new
24 hours start.
For example, for NIFTY on 24 September 2026:
| Request | Tokens |
|---|---|
symbol/info?symbol=NIFTY&date=2026-09-24 at 10:00 AM | 1 |
| The same request at 4:00 PM | 0 |
option-chain?symbol=NIFTY&date=2026-09-24 at 4:05 PM | 1 (a different endpoint) |
option-chain?symbol=NIFTY&date=2026-09-24&expiry=2026-09-29 at 4:10 PM | 0 (the same expiry the default resolved to) |
symbol/info?symbol=NIFTY&date=2026-09-24 at 10:30 AM the next day | 1 (the 24 hours have passed) |
How historical candles are charged
/analysis/candles/historical can return up to 30 days
in one call, so a flat price per call wouldn't be fair either way. You pay for the data you
get instead:
- 1 token per symbol per past day that has candles. The current trading day, weekends, market holidays, and days with no data for that contract are free.
- Resolution doesn't matter. 1-minute and 15-minute candles for the same symbol and day cost the same.
- Free again for 24 hours. Once a symbol and day is charged, asking for it again within 24 hours of that charge costs nothing, in any range and at any resolution.
- All or nothing. If your balance can't cover every new day in the request, nothing
is charged, no candles come back, and you get a
402whoserequiredis the number of new days.
Here's how that plays out for the NIFTY 25100 CE (NIFTY26092925100CE):
| Request | Tokens |
|---|---|
| 14 to 20 September (Monday to Sunday) | 5 (Saturday and Sunday are free) |
| The same range again an hour later | 0 |
| 17 to 24 September, the same day | 4 (17 and 18 are already paid; 21 to 24 are new) |
| 14 to 20 September again two days later | 5 (the 24 hours have passed) |
14 to 20 September for NIFTY26092925100PE | 5 (a different symbol) |
/analysis/candles/intraday follows the same rule. After 3:40 PM it serves today's session,
which is free. Before then it serves the previous session, which is charged 1 token per
symbol and shares the same 24-hour window, so a day paid through either candle endpoint is
free through the other.
When a call costs nothing
Current-day data is always free. For historical data, you're only charged for calls that succeed:
- Calls rejected before they run are never charged. That covers a missing or expired
token (
401), no plan that allows API access (403), and a rate limit (429). - A call that runs and then fails with any status of
400or above is refunded automatically. A422for a bad date or a404for an unknown symbol nets to zero. - A call you can't afford returns
402and charges nothing.
Refunds show up in your token ledger, so you can always match a charge to its refund.
Estimate what your script will use
Work out your daily usage before you leave a script running. Two common patterns:
A live option chain poller. Current-day data is free, so polling the NIFTY chain all session costs 0 tokens. The rate limits are what bound it: the session runs from 9:15 AM to 3:30 PM (375 minutes), so a 10-second poll is 2,250 requests a day, most of the default daily limit of 3,000.
A weekly backtest pull. You pull 5-minute historical candles for 5 NIFTY strikes, calls and puts, over 20 trading days. That's 10 symbols x 20 days = 200 tokens. If you tweak the strategy and re-run the pull within 24 hours, the same 200 candle days cost nothing.
Historical candles don't change once a session has closed. Save what you pull to a file or database, and you'll never pay for the same day twice.
Running out of tokens (402)
When your balance can't cover a call, you get 402 and nothing is charged. action is
external_api.candle_day for every historical charge. For candles, required is the number
of new days in the request. This response uses Stolo's general error format, not the usual
API envelope, so check body.error_code:
{
"error": true,
"message": "You don't have enough Stolo Tokens for this action",
"status": 402,
"body": {
"error_code": "INSUFFICIENT_TOKENS",
"required": 1,
"balance": 0,
"action": "external_api.candle_day"
},
"date": "2026-09-28T04:12:09.512Z"
}
Retrying won't help. Top up and the next call works straight away, with the same token. Trading calls are unaffected, since they don't use tokens.
Checking your balance and usage
Everything your API app spends shows up in the Stolo app:
- Log in to Stolo and open Account, then Stolo Tokens.
- The top card shows your available balance. Press Buy tokens to top up.
- Where your tokens went groups your spending. API usage appears as Historical API Data (past-date symbol info, option chain, and candles).
- The Usage and Ledger lists show every charge and refund, newest first.
Buying tokens is a one-time purchase, not a subscription, and larger packs cost less per token. Stolo Tokens have no expiry date: once bought, they stay in your account for as long as the account exists, so unused tokens carry over until you spend them. See the current packs on the buy tokens page.
Check your Stolo Tokens balance
See what your API calls have used and top up before your script runs out.
Open Stolo Tokens