For developers and analysts
Iran market data API, straight into your app
The data Fundai runs on, from Codal statements and daily trading to monthly sales and the commodity exchange, behind one API. Credits come off only for requests that get a proper answer.
API changes and versions- 100 free credits with your first key (verified mobile)
- Pay for what you use
- Errors are free
Quick start
Your first data in a few minutes.
- Create a key and get 100 free creditsIn the API tab of your profile. The key is shown once, so save it right away.
- Send your first requestStart with
/me/. It is free and shows your remaining credit. - Buy credit when you need itOn the pricing page, as much as you need. Credit never expires.
curl -H "Authorization: Bearer $FUNDAI_API_KEY" \
"https://fundai.ir/api/data/v1/companies/foulad/prices/?from=1405-01-01&limit=100"Authentication
Send the key in the Authorization header of every request. If your tool can't set it, the X-API-Key header works too.
Authorization: Bearer fai-api_…Send the key from a server only. A request from a browser is refused, because a key inside a web page is visible to anyone.
If you think a key leaked, disable it in the API tab of your profile straight away and create a new one. You can have up to 3 live keys and 3 test keys at once.
Sandbox
- You don't need credit to build and test your app. Create a test key in the API tab of your profile. Test keys start with
fai-test_and every endpoint answers them with the sample data on this page, in the real response shape. - It is sample data, not real market data. The answer carries
meta.sandboxand theX-Sandboxheader, bothtrue. - No request is charged, even with a zero balance.
- It allows 10 requests a minute and 500 a day, counted apart from your live key.
- Paging works too:
next_cursorgives one more page, then ends. - MCP works with a test key as well. When your app is ready, swap in a live key.
Credits and pricing
Every request is charged in one of two ways.
By the period: statements, manufacturing overhead, trailing twelve months, the monthly reports (sales and production, raw materials, energy, currency), IME monthly, weekly and cumulative totals, and portfolios. You pay once for each period in the answer, however many rows it holds. A month of the monthly activity report, one statement for one period, a quarter and a portfolio sheet are each one period. Three years of a company's sales and production, for example, is 36 months and costs 36 times the monthly price. Here limit counts periods, and no period is split across two pages.
By the row: everything else. Daily trading, technical indicators, index history, market money flow and Codal letters are priced per 30 rows. The returns of the markets are priced per month. Dividends, trading states and the live order book are priced per request, the order book history and trades per trading day of one symbol, and the rest per 20 rows. Daily trading adjusted for capital raises and dividends (adjusted=true) costs twice as much: 6 credits per 30 trading sessions instead of 3.
Without limit, an answer is one period or one block, so the price is taken once. What each request cost is in its X-Credits-Charged header.
What is free
- Any request that fails, from a wrong key to a company we can't find.
- Repeating the same GET within 60 seconds. If the connection drops and you resend, you don't pay twice.
- Resending a request with the same Idempotency-Key, for 24 hours.
- An answer that hasn't changed: after the free-repeat window, send the previous ETag as If-None-Match and get a free 304.
- An empty answer: if we have no such data for the company, or no rows fit your filters, nothing is charged and meta.empty says why.
- The /me/, /datasets/, /usage/ and /indexes/ endpoints.
How we make sure your credit is charged right
- Credit comes off only once the answer is fully built. If anything fails along the way, nothing is charged.
- Taking the credit and recording the call happen together. If two requests arrive together and your credits cover only one, only one gets an answer, and the balance never goes below zero.
- Every request, free or charged, is logged in the API tab of your profile with its id. If an answer never reached you, send its X-Request-Id to support and we will look into it and refund it if needed.
Rate limits
Each account's limits depend on its usage tier. Everyone starts at tier 1, and the more you use the API, the higher your tier goes. Only the credits you spend count, not the credits you buy. A new tier takes effect within 10 minutes.
| Limit | Value | What it means |
|---|---|---|
Free repeatSend the same request again within this window and it costs nothing. | 60 seconds | Send the same request again within this window and it costs nothing. |
Idempotency-KeyRepeat a request with the same Idempotency-Key within this time and you get the first answer again, free. | 24 hours | Repeat a request with the same Idempotency-Key within this time and you get the first answer again, free. |
Companies a monthEach Jalali month you can read this many different companies. A company you already read doesn't count again until the month ends. Daily trading, technical indicators, the whole-market datasets, the order book and trades don't count. For more, talk to us about an enterprise contract. | 50 companies | Each Jalali month you can read this many different companies. A company you already read doesn't count again until the month ends. Daily trading, technical indicators, the whole-market datasets, the order book and trades don't count. For more, talk to us about an enterprise contract. |
HistoryOlder rows are left out, and `meta.history_from` says where the answer starts. Daily trading, technical indicators, market indexes, market money flow and trading states come with their whole history, and the order book and trades with their last 30 days. For the rest, the full history comes with an enterprise contract. | 3 years | Older rows are left out, and `meta.history_from` says where the answer starts. Daily trading, technical indicators, market indexes, market money flow and trading states come with their whole history, and the order book and trades with their last 30 days. For the rest, the full history comes with an enterprise contract. |
Past a limit you get a 429, which costs nothing. Its Retry-After header says how many seconds to wait. Better still, pace yourself with X-RateLimit-Remaining so you never hit the limit.
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
{"detail": "api-rate-limited"}Need higher limits? Write to cooperation@fundai.ir.
Response format
- Shape
- Lists come as {"data": [...], "next_cursor": ..., "meta": {...}} and one item as {"data": {...}, "meta": {...}}. Numbers carry at most four decimals; counts, volumes and rial amounts carry none.
- Last updated
- Every answer says in meta.updated_at when its data last changed; for one company, when that company's data last changed. When you show someone a figure, tell them this time too.
- Paging
- For the next page, send next_cursor back as cursor. When it is null you have reached the end. The order is fixed, so a new row arriving mid-walk doesn't shift the others.
- Dates
- Every date comes twice: date in ISO Gregorian and date_jalali in the Iranian calendar. from and to accept either.
- Units
- The unit is in the field name: close_rial is rial, value_million_rial is million rial. Percents are percents: 12.5 means 12.5%.
- Unknown values
- A figure we don't have is null, never zero and never a dash.
- Company id
- In paths, {company} takes the company's slug or its symbol, in any spelling Codal and TSETMC use.
- Raw or processed
- Raw data is what Codal, TSETMC or the commodity exchange published. Processed data is built by us: standardised products, trailing twelve months, ratios and the screener.
- Staying in sync
- To keep your own copy current, fetch only from the last date you have with from. There is no need to read the whole history again.
Errors
Every error comes as {"detail": "..."} and costs nothing. For a bad parameter, the errors field names it.
Data reference
Every endpoint with its path, price, parameters, response fields and a real example.
Using it with AI
If you work with ChatGPT, Claude or another assistant, you don't need to explain this page to it. llms.txt has every rule and dataset in the form models read easily, and the OpenAPI file can go straight into your tools.
What the guide tells the model
- Never print or store the key.
- Check the balance with /me/ before a large job.
- Fetch only the company and range the question needs.
- On a 429, wait and then retry.
- Report every figure with its unit and period, and never forecast prices.
Give this to your assistant
Use the Fundai Data API to answer. First read the guide at https://fundai.ir/api/data/v1/llms.txt and follow its rules. The API key is in the FUNDAI_API_KEY environment variable; never write it anywhere.Use it over MCP
If your assistant speaks MCP, like Claude, Cursor, Copilot, Codex or Gemini CLI, connect Fundai to it directly. The assistant then fetches the data itself, with no code on your side.
Server address
POSThttps://fundai.ir/api/data/v1/mcp/
Fundai's MCP server lives at this address. It takes POST over Streamable HTTP, and its messages are JSON-RPC.
What to know
- Send the same API key in the
Authorization: Bearerheader. No separate key is needed. In ChatGPT and Claude.ai you can sign in with your Fundai account instead. - Each tool is named after a dataset, such as
prices,statementsandscreener. Theme,datasetsandusagetools are free. - Each tool call costs exactly what the matching API request costs. A call that fails costs nothing.
Connect ChatGPT and Claude with your Fundai account
You don't need to copy an API key anywhere to connect Fundai to ChatGPT or Claude. You sign in with your Fundai account and allow access (OAuth). From then on the service works with an access token that reaches only Fundai's MCP tools, and you can cancel it anytime.
ChatGPT
- Open ChatGPT in your browser and go to Settings › Plugins.
- Press + and choose Add custom MCP server.
- Name it Fundai and enter
https://fundai.ir/api/data/v1/mcp/under Connection. - Set authentication to OAuth, accept the warning and press Create as a plugin.
- Fundai's sign-in page opens. Sign in and press "Allow".
- In a new chat, reach Fundai's tools with @Fundai.
For now this is fully available on Business and Enterprise/Edu accounts, and on Enterprise/Edu an admin has to allow it. If you don't see Add custom MCP server, your ChatGPT account doesn't have it yet.
Claude
- In Claude.ai, go to Customize › Connectors.
- Press Add and choose Add custom connector.
- Name it Fundai, enter
https://fundai.ir/api/data/v1/mcp/and press Continue. - Choose Sign in now. Fundai's page opens. Sign in and press "Allow".
Every Claude plan has it. Free allows one custom connector. On Team and Enterprise, an owner adds it under Organization settings › Connectors.
Each request is charged to your API credit, just like a key. The connection renews itself; there is nothing to do. Up to 5 apps can be connected at once, and you can end any of them anytime in your profile's API tab.
Fundai has no access to your conversations, files or any other part of your ChatGPT or Claude account, and does not give them your name, number or email. We log only the data requests the app makes to Fundai, to work out the cost and show you your usage history.
If Fundai's page doesn't open, or no tools appear after you sign in, remove the connection in that service and add it again. If it still fails, tell support.
Connect your assistant
Run this in a terminal, with your own key in place of YOUR_KEY.
claude mcp add --transport http \
fundai https://fundai.ir/api/data/v1/mcp/ \
--header "Authorization: Bearer YOUR_KEY"Instructions for the assistant
Put this in your project's CLAUDE.md so the assistant knows the rules, the costs and every dataset.
Keep the file that holds your key out of code repositories and anywhere public. If it leaks, disable it in the API tab of your profile.
Frequently asked questions
What data does the Fundai API give me?
The directory of Tehran Stock Exchange and Fara Bourse companies and industries, each symbol's daily trading from TSETMC and its technical indicators, market indexes and the whole market's money flow, each symbol's trading state, the live order book and its history, every trade, the bourse's monthly returns beside the dollar, gold, housing and inflation, Codal financial statements and trailing four-quarter sums, daily financial ratios, monthly sales and production, commodity exchange trades, dividends voted at annual meetings, Codal filings, and the portfolios of funds and investment companies. You can also run the site's multi-step screener through the API.
Does Fundai's API have technical indicators?
Yes. Simple and exponential moving averages, RSI, MACD, stochastic, Bollinger bands, ATR, ADX, CCI, Williams %R, MFI, OBV, Ichimoku and parabolic SAR, for every trading day of every symbol, with the whole history and on adjusted prices. During market hours today's values refresh a few minutes after each price update. Every 30 trading days cost 5 credits, and commercial use is free with no agreement. Each field is described under «Technical indicators» in the data reference.
Does Fundai's API have whole-market data?
Yes. The daily history of the main index, the equal-weighted index, Fara Bourse's main index and the industry indexes, individuals' money flow and the count of symbols up and down across the market, and each symbol's trading state, open or halted. Indexes come with the whole history from 1387 and cost 3 credits per 30 trading days; money flow, also from 1387, costs 15 credits per 30 trading days. Trading states cost 1 credit per request, and all of them are free for commercial use with no agreement. The bourse's monthly returns beside the dollar, the gold coin, gold, fixed-income funds, housing and inflation cover the last three years and cost 20 credits per month.
Does Fundai's API have the order book and trades?
Yes. Each symbol's five best buy and sell levels, with the price, volume, number of orders and value at each, the buy and sell queue and the order totals, are refreshed every 2 seconds while the market is open. One request returns up to 50 symbols, or every symbol with symbols=all, at 0.2 credit a symbol. If you need the changes live, the order book, price and flow streams push each one as it happens, at 0.2 credit a symbol per trading day, for every symbol at the same rate. Every change to the order book and every trade of a day, with time, volume and price, are there for the last 30 days, at 5 credits a symbol a day. All of it is free for commercial use with no agreement.
How is the API priced?
You buy credit, and every successful request takes that dataset's fixed price off it. Statements, manufacturing overhead, trailing twelve months, the monthly reports (sales and production, raw materials, energy, currency), IME monthly, weekly and cumulative totals, and portfolios are priced by the period (a month of the activity report, one statement for one period); everything else by the row: 30 rows of daily trading, technical indicators, index history, market money flow or Codal letters, the returns of the markets per month, dividends, trading states and the live order book per request, a trading day of one symbol for the order book history and trades, 20 rows of the rest. The price table on this page has each dataset's price. A request that fails costs nothing, and repeating the same request within 60 seconds is not charged again.
How many credits will my use take a month?
Use the calculator in the Credits and pricing section of this page. Pick the data you need, say for how many symbols and how often, and it shows the credits for each run and for a month. For example, the daily trading of 10 symbols, reading their last 30 trading days every trading day, is 30 credits a run and 600 credits a month. It then suggests the package that covers your first month or several, with the volume discount on larger ones. Credit never expires.
Can I try the API before I buy?
Yes. Your first key, created in the API tab of your profile, comes with 100 free credits that read real data. For example, a symbol's last 30 trading days cost 3 credits in one request. It is given once, to accounts with a verified mobile number.
Where do I get an API key?
Sign in to Fundai and open the API tab in your profile. You buy credit and create keys there. A key is shown only once, so store it somewhere safe straight away. You can have up to 3 active keys at a time.
What are the rate limits?
Each account's limits depend on its usage tier. A new account is at tier 1, with 30 requests per minute (RPM), 1,000 requests per day (RPD) and 2 concurrent requests. The more you use the API, the higher your tier and your limits go. Only the credits you spend count, not the credits you buy. A new tier takes effect within 10 minutes. Going over a limit returns a 429, which costs nothing. If you need higher limits sooner, tell support.
How many companies can I read?
Each Jalali month you can read up to 50 different companies. A company you already read doesn't count again until the month ends, so an app that follows a set of symbols stays well inside it. The company list, industries, daily trading, technical indicators, the whole-market datasets (indexes, money flow, the returns of the markets and trading states), the order book, trades and the multi-step screener don't count toward it, so you can read daily trading, indicators, the order book and trades for every symbol. For every company's data, talk to us about an enterprise contract.
Can I connect the API to ChatGPT or Claude?
Yes. ChatGPT and Claude connect to Fundai's MCP server by signing in to your Fundai account, then fetch the data themselves. The steps are in the MCP section of this page. In ChatGPT this is on Business and Enterprise/Edu accounts only, for now. Claude Code, Cursor, Copilot in VS Code, Windsurf, Codex and Gemini CLI connect with an API key. If your assistant has no MCP, give it the llms.txt guide. An assistant's request costs the same as the API request.
What is the difference between raw and processed data?
Raw data is what Codal, TSETMC or the commodity exchange published, with the same figures and units. Processed data is built by Fundai from the raw data: product names standardised, the last four quarters summed and ratios computed. Each dataset's kind is in the price table.
How fresh is the data and how far back does it go?
It is the data the Fundai site shows, and just as fresh: daily trading is added after each trading day and Codal filings after they are published. The live order book is refreshed every 2 seconds while the market is open, and the order book history and trades reach 30 days back. Daily trading, technical indicators, indexes, market money flow and trading states come with their whole history; for everything else you get the last 3 years. You choose the range with from and to. The full history of the rest comes with an enterprise contract, except the returns of the markets, which reach the last three years on every plan.
Can I use the API in my product or business?
It is free for personal use. To use the data in a product, site or service for others, or to sell it, send a request from the enterprise page and we will agree the terms. Daily trading, technical indicators, market indexes, market money flow, trading states, the order book and its streams, the whole market, trades and a company's card are the exception: free for commercial use, with no agreement.
How do I buy credit, and does it expire?
On the pricing page, type how many credits you want or pick a common amount, and pay by bank card through the online payment gateway. Credit never expires and stays until you use it.
Support
A question, or data you need that isn't here? Send a support ticket, write to support@fundai.ir or talk to support on Telegram.
