Iranian Rial Exchange Rate API: The Complete Guide to IRR and Toman Rates

If you have ever pulled “USD/IRR” from a mainstream currency API and shown it to users in Iran, you probably got a complaint within minutes: the number did not match anything they saw in the market. Iran has several exchange rates at the same time, two currency units in daily use and a market without a central exchange. This guide explains what an Iranian Rial exchange rate API has to deal with, and how to integrate one correctly.

Why Iranian exchange rates are different

Several rates at once

Iran runs official mechanisms for certain imports and exports alongside a free market where individuals and most businesses trade. The official rate is usually well below the free-market rate. Global providers often source the official figure, which is why it looks “wrong” to people in Iran. The full explanation is in Iran official vs free market rate.

No central order book

The free market is spread across exchange offices, wholesale traders, trading groups, border markets and crypto exchanges. There is no single ticker to read. A reliable rate has to be built from many concurrent quotes, which is what EZRate’s pipeline does: how EZRate aggregates OTC market data.

Rial and Toman

The Rial (IRR) is the legal unit; the Toman (10 Rial) is what people say and what most prices are quoted in. Mixing them up is the most common fintech bug in Iran. See IRR vs Toman for developers.

What the API gives you

Every response has a data object and a meta object with as_of, freshness_sec and quote. The full schema of each endpoint is in the JSON reference, and you can make your first request in five minutes with the quickstart.

curl -s -H "X-API-Key: $EZRATE_KEY" \
  "https://api.ezrate.me/v1/rates?symbols=usd,eur,aed,g18,emami,usdt&lang=en"

{
  "data": [
    { "symbol": "usd", "code": "USD", "name": "US Dollar", "category": "fiat",
      "market": "tehran", "buy": 0, "sell": 0, "change_pct": 0.12,
      "sources": 13, "low_sources": false, "updated_at": "…", "quote": "IRT" }
  ],
  "meta": { "as_of": "…", "freshness_sec": 60, "quote": "IRT" }
}

How the numbers are built

Every minute EZRate collects quotes from many independent sources, keeps only the recent ones, drops anything more than about 1% away from the median and publishes a weighted median of what remains. When fewer than five valid sources are active (late at night, on holidays), the last good rate is kept and flagged with low_sources: true. A jump guard stops sudden unconfirmed spikes. The method is public on the methodology page, and the statistics behind it are covered in outlier detection in price feeds.

Assets you can query

Choosing the unit: `quote`

By default prices are in Toman (IRT). Pass quote=IRR for Rial, or any asset symbol to price everything in that asset, e.g. quote=usd returns gold in free-market dollars and quote=usdt prices crypto in Tether. Never multiply by ten in your own code if the API can do it; the unit is then recorded in the response and your logs.

Integration architecture

1. Server-side only. Never put your key in browser JavaScript or a mobile binary: securing financial API keys.
2. Cache for at least meta.freshness_sec. One cached response can serve every visitor: Laravel caching shows the pattern.
3. Handle errors and staleness. Respect 429 and Retry-After, keep the last good value, show updated_at: failover strategies.
4. Display honestly. Show buy/sell, the unit, the update time and a low-source badge when needed.

Tutorials by stack

Historical data

/history/{symbol} returns hourly or daily candles (t, o, h, l, c, UTC timestamps, based on the sell rate). Depth depends on your plan. For research use cases see historical USD/IRR data.

Plans and limits

Plans differ by request quota, data freshness and history depth. Limits are returned in X-RateLimit-* headers and in /usage. Current plans are listed on the API page.

Related live rates: US dollar rate, 18K gold price, Emami coin price.