# Iran Rial Market API
> Live free-market (bazaar) prices for the Iranian rial against foreign currencies, gold and gold coins. Iran's official rate is fixed and unused in practice; the real economy trades on the open bazaar rate, which is what this API exposes. The price endpoint returns one instrument's latest close/open/high/low, day change and date — in both rial and toman. The currencies endpoint returns every foreign currency (USD, EUR, GBP, AED, TRY, CNY, RUB …) against the rial at once. The gold endpoint returns Iran's gold market — the global ounce, 18k and 24k gram, the mesghal, and the famous gold coins (Emami, Bahar Azadi, half, quarter, gerami). The history endpoint returns an instrument's daily OHLC series. Read live, nothing stored. This is Iran's own free-market rial/gold/coin layer — distinct from official central-bank feeds and from other countries' parallel-dollar APIs.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/irr-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 60,000 calls/Mo, 12 req/s
- **Pro** ($22/Mo) — 300,000 calls/Mo, 35 req/s
- **Scale** ($52/Mo) — 2,000,000 calls/Mo, 110 req/s

## Endpoints

### Price

#### `GET /v1/price` — One instrument's latest price by symbol

**Parameters:**
- `symbol` (query, required, string) — Instrument symbol (usd, eur, ounce, coin_emami …) Example: `usd`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irr-api/v1/price?symbol=usd"
```

**Response:**
```json
{
    "data": {
        "low": 1757800,
        "date": "2026/06/10",
        "high": 1785200,
        "name": "US Dollar",
        "open": 1785100,
        "unit": "IRR",
        "close": 1758050,
        "change": 32100,
        "source": "tgju.org",
        "symbol": "usd",
        "category": "currency",
        "change_pct": 1.83,
        "close_toman": 175805,
        "date_jalali": "1405/03/20"
    },
    "meta": {
        "timestamp": "2026-06-10T22:57:35.748Z",
        "request_id": "375895f3-0cb1-4ac7-af2b-eb0467b8b6b5"
    },
    "status": "ok",
    "message": "Price retrieved successfully",
    "success": true
}
```

### Currencies

#### `GET /v1/currencies` — Every foreign currency vs the rial

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irr-api/v1/currencies"
```

**Response:**
```json
{
    "data": {
        "base": "IRR",
        "count": 11,
        "source": "tgju.org",
        "currencies": [
            {
                "low": 2354800,
                "date": "2026/06/10",
                "high": 2397200,
                "name": "British Pound",
                "open": 2392100,
                "unit": "IRR",
                "close": 2355100,
                "change": 45700,
                "symbol": "gbp",
                "category": "currency",
                "change_pct": 1.95,
                "close_toman": 235510,
                "date_jalali": "1405/03/20"
            },
            {
                "low": 2201100,
                "date": "2026/06/10",
                "high": 2240800,
                "name": "Swiss Franc",
                "open": 2236400,
                "unit": "IRR",
                "close": 2202400,
                "change": 40000,
                "symbol": "chf",
                "category": "currency",
                "change_pct": 1.82,
                "close_toman": 220240,
                "date_jalali": "1405/03/20"
            },
            {
                "low": 2031000,
                "date": "2026/06/10",
                "high": 2065800,
                "name": "Euro",
                "open": 2063100,
                "unit": "IRR",
                "close": 2031300,
                "change": 39000,
                "symbol": "eur",
                "category": "currency",
                "change_pct": 1.93,
       
…(truncated, see openapi.json for full schema)
```

### Gold

#### `GET /v1/gold` — Iran gold market — ounce, gram, coins

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irr-api/v1/gold"
```

**Response:**
```json
{
    "data": {
        "gold": [
            {
                "low": 4071.25,
                "date": "2026/06/10",
                "high": 4262.23,
                "name": "Gold Ounce (global)",
                "open": 4078.86,
                "unit": "USD",
                "close": 4260.4,
                "change": -180.73,
                "symbol": "ounce",
                "category": "gold",
                "change_pct": -4.43,
                "date_jalali": "1405/03/20"
            },
            {
                "low": 177513000,
                "date": "2026/06/10",
                "high": 179249000,
                "name": "Gold 18k (gram)",
                "open": 179143000,
                "unit": "IRR",
                "close": 179249000,
                "change": -108000,
                "symbol": "gram_18k",
                "category": "gold",
                "change_pct": -0.06,
                "close_toman": 17924900,
                "date_jalali": "1405/03/20"
            },
            {
                "low": 236681000,
                "date": "2026/06/10",
                "high": 238996000,
                "name": "Gold 24k (gram)",
                "open": 238854000,
                "unit": "IRR",
                "close": 238996000,
                "change": -145000,
                "symbol": "gram_24k",
                "category": "gold",
                "change_pct": -0.06,
                "close_toman": 23899600,
                "date_jalali": "1405/0
…(truncated, see openapi.json for full schema)
```

### History

#### `GET /v1/history` — Daily OHLC series for an instrument

**Parameters:**
- `symbol` (query, required, string) — Instrument symbol Example: `usd`
- `limit` (query, optional, string) — Rows (1-365) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irr-api/v1/history?symbol=usd&limit=30"
```

**Response:**
```json
{
    "data": {
        "name": "US Dollar",
        "unit": "IRR",
        "count": 30,
        "source": "tgju.org",
        "symbol": "usd",
        "history": [
            {
                "low": 1757800,
                "date": "2026/06/10",
                "high": 1785200,
                "open": 1785100,
                "close": 1758050,
                "date_jalali": "1405/03/20"
            },
            {
                "low": 1751800,
                "date": "2026/06/09",
                "high": 1770200,
                "open": 1753000,
                "close": 1769800,
                "date_jalali": "1405/03/19"
            },
            {
                "low": 1772800,
                "date": "2026/06/08",
                "high": 1788200,
                "open": 1774000,
                "close": 1782150,
                "date_jalali": "1405/03/18"
            },
            {
                "low": 1747800,
                "date": "2026/06/07",
                "high": 1780200,
                "open": 1780100,
                "close": 1747950,
                "date_jalali": "1405/03/17"
            },
            {
                "low": 1734800,
                "date": "2026/06/06",
                "high": 1755200,
                "open": 1749900,
                "close": 1735000,
                "date_jalali": "1405/03/16"
            },
            {
                "low": 1737800,
                "date": "2026/06/03",
                "high": 1748200,
   
…(truncated, see openapi.json for full schema)
```

### Symbols

#### `GET /v1/symbols` — All supported symbols

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irr-api/v1/symbols"
```

**Response:**
```json
{
    "data": {
        "count": 21,
        "source": "tgju.org",
        "symbols": [
            {
                "name": "US Dollar",
                "unit": "IRR",
                "symbol": "usd",
                "category": "currency"
            },
            {
                "name": "Euro",
                "unit": "IRR",
                "symbol": "eur",
                "category": "currency"
            },
            {
                "name": "British Pound",
                "unit": "IRR",
                "symbol": "gbp",
                "category": "currency"
            },
            {
                "name": "UAE Dirham",
                "unit": "IRR",
                "symbol": "aed",
                "category": "currency"
            },
            {
                "name": "Turkish Lira",
                "unit": "IRR",
                "symbol": "try",
                "category": "currency"
            },
            {
                "name": "Canadian Dollar",
                "unit": "IRR",
                "symbol": "cad",
                "category": "currency"
            },
            {
                "name": "Australian Dollar",
                "unit": "IRR",
                "symbol": "aud",
                "category": "currency"
            },
            {
                "name": "Swiss Franc",
                "unit": "IRR",
                "symbol": "chf",
                "category": "currency"
            },
            {
                "name": "Ch
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irr-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Prices in IRR (rial); toman = rial / 10. Gold ounce quoted in USD.",
        "source": "tgju.org market API (api.tgju.org, live)",
        "service": "irr-api",
        "usd_irr": 1758050,
        "endpoints": {
            "GET /v1/gold": "Iran's gold market — ounce, 18k/24k gram and gold coins.",
            "GET /v1/meta": "This document.",
            "GET /v1/price": "One instrument's latest close/open/high/low, day change and date (symbol=usd).",
            "GET /v1/history": "An instrument's daily OHLC series (symbol=usd, limit=30).",
            "GET /v1/symbols": "All supported symbols.",
            "GET /v1/currencies": "Every foreign currency vs the rial at once."
        },
        "description": "Live free-market (bazaar) prices for the Iranian rial against foreign currencies, gold and gold coins, from a public Iranian market feed. Iran's official rate is fixed and unused in practice; the real economy trades on the open bazaar rate exposed here. The price endpoint returns one instrument's latest close/open/high/low, day change and date (rial and toman); the currencies endpoint returns every foreign currency (USD, EUR, GBP, AED, TRY, CNY …) vs the rial at once; the gold endpoint returns the global ounce, 18k/24k gram and the famous gold coins (Emami, Bahar Azadi, half, quarter, gerami); the history endpoint returns an instrument's daily OHLC series. Live, no key, nothing stored. Distinct from official central-bank feeds and f
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/irr-api
OpenAPI spec: https://www.oanor.com/api/irr-api/openapi.json