# بورس کالا

> شش endpoint بورس کالای ایران در API روشا؛ گواهی سپرده کالایی (سکه، شمش طلا، نقره، مس)، اختیار معامله و آتی، و معاملات بازار فیزیکی و صادراتی، با واحدها و منبع هر عدد.
> Source: https://poolick.ir/docs/api/ime/

روشا از بورس کالای ایران (ime.co.ir) فقط داده‌هایی را می‌گیرد که در TSETMC نیست: گواهی سپرده کالایی، قراردادهای اختیار معامله و آتی، و معاملات بازار فیزیکی و صادراتی. گواهی‌های کالایی مثل زعفران، صندوق‌های کالایی مثل «عیار» و قراردادهای سلف در TSETMC نماد دارند؛ آن‌ها را از [`/v1/instruments`](/docs/api/instruments/) بگیرید.

| endpoint | کاربرد | خانواده |
|---|---|---|
| `GET /v1/ime/contracts` | فهرست و جست‌وجوی قراردادها با آخرین ردیف روزانه | همیشه مجاز |
| `GET /v1/ime/contracts/{code}` | مشخصات قرارداد و بازهٔ سابقه | همیشه مجاز |
| `GET /v1/ime/contracts/{code}/daily` | سابقهٔ روزانهٔ قرارداد | `history` |
| `GET /v1/ime/contracts/{code}/quote` | آخرین وضعیت؛ در ساعات بازار زنده با دفتر سفارش | `intraday` |
| `GET /v1/ime/contracts/{code}/intraday` | همهٔ تغییرات تابلو در یک روز | `intraday` |
| `GET /v1/ime/physical` | عرضه‌های بازار فیزیکی و صادراتی در یک بازه | `history` |

## قرارداد چطور شناسایی می‌شود؟

هر قرارداد با کد خودِ بورس کالا شناخته می‌شود (`contract_code`) و بزرگی و کوچکی حروفش مهم نیست.

| نوع (`kind`) | نمونهٔ کد | چیست |
|---|---|---|
| `cdc` | `GoldCoin`، `GoldBar`، `SilverBar`، `CopperCthd` | گواهی سپرده کالایی: سکهٔ تمام بهار آزادی، شمش طلا، شمش نقره، مس کاتد |
| `option` | `TLTR06C100` | اختیار معامله؛ `C` خرید و `P` فروش، با قیمت اعمال در `strike` |
| `future` | `COPME05` | قرارداد آتی |

## هر عدد از کجا می‌آید؟

| داده | منبع در بورس کالا | از |
|---|---|---|
| اختیار معامله، روزانه | گزارش آمار روزانه (`source: "report"`) | آذر ۱۳۹۵ |
| آتی، روزانه | گزارش آمار روزانه (`source: "report"`) | تیر ۱۳۸۷ |
| گواهی سپرده، روزانه | وضعیت پایانی تابلوی برخط (`source: "board"`) | آبان ۱۴۰۵ |
| بازار فیزیکی و صادراتی | گزارش آمار معاملات | شهریور ۱۳۹۴ |
| تغییرات درون‌روز | تابلوی برخط، از ۸:۳۰ تا ۱۸:۰۵ روزهای معاملاتی | آبان ۱۴۰۵ |

**بورس کالا سابقهٔ روزانهٔ گواهی سپرده را منتشر نمی‌کند.** روشا وضعیت پایانی تابلو را هر روز معاملاتی ثبت می‌کند؛ این سابقه از آبان ۱۴۰۵ شروع می‌شود و روز ازدست‌رفته را نمی‌شود بعداً از بورس کالا گرفت. بازار آتی بورس کالا از ۲۹ اردیبهشت ۱۴۰۵ معامله‌ای نداشته است.

## فهرست قراردادها را چطور بگیرم؟

`GET /v1/ime/contracts` قراردادها را با آخرین ردیف روزانه‌شان برمی‌گرداند؛ اول گواهی‌های سپرده، بعد بیشترین ارزش معامله.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `q` | رشته | – | جست‌وجو در کد، شرح و دارایی پایه، مثلاً `سکه` یا `شمش طلا` |
| `kind` | رشته | – | `cdc`، `option` یا `future` |
| `active` | بولی | `true` | `true` فقط قراردادهای سررسیدنشده؛ `false` همه |
| `limit` | عدد صحیح | `50` | از `1` تا `500` |
| `offset` | عدد صحیح | `0` | ردیف‌هایی که از ابتدای فهرست رد می‌شود |

```bash
curl -G "https://poolick.ir/v1/ime/contracts" \
  -d "kind=cdc" -d "limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

هر عضو `items` این فیلدها را دارد:

| فیلد | معنا |
|---|---|
| `contract_code`، `kind` | کد و نوع قرارداد |
| `description`، `underlying` | شرح قرارداد و دارایی پایه (مثلاً `سکه طلا`) |
| `option_type`، `strike` | فقط اختیار معامله: `call` یا `put`، و قیمت اعمال به ریال |
| `contract_size` | اندازهٔ قرارداد |
| `delivery_date` | سررسید؛ برای گواهی سپرده آخرین روز معاملاتی نماد |
| `active` | آیا سررسید نگذشته است |
| `latest` | آخرین ردیف روزانه با معامله یا قیمت تسویه؛ فیلدهای جدول بعد |

## سابقهٔ روزانه چه فیلدهایی دارد؟

`GET /v1/ime/contracts/{code}/daily` ردیف‌ها را از قدیم به جدید برمی‌گرداند. `start` و `end` بازه را محدود می‌کنند و `limit` (پیش‌فرض `1000`، سقف `5000`) N روز آخر بازه را نگه می‌دارد.

```bash
curl "https://poolick.ir/v1/ime/contracts/GoldCoin/daily?limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
{
  "contract_code": "GoldCoin",
  "kind": "cdc",
  "rows": [
    {
      "d": "2026-11-15",
      "open": 2485000000.0,
      "high": 2488000000.0,
      "low": 2465000500.0,
      "close": 2484897000.0,
      "avg_price": 2477541002.3809,
      "settlement": null,
      "prev_settlement": 2517065181.0,
      "volume": 672.0,
      "value": 1664907554000.0,
      "trades": 233,
      "open_interest": 488998.0,
      "oi_change": -286.0,
      "buyers": 69,
      "sellers": 44,
      "buy_i_volume": 656.0,
      "buy_n_volume": 16.0,
      "sell_i_volume": 209.0,
      "sell_n_volume": 463.0,
      "buy_i_value": null,
      "buy_n_value": null,
      "sell_i_value": null,
      "sell_n_value": null,
      "source": "board",
      "jdate": "1405-08-24"
    }
  ]
}
```

| فیلد | واحد | معنا |
|---|---|---|
| `d`، `jdate` | میلادی ISO، شمسی | روز معاملاتی |
| `open`، `high`، `low`، `close` | ریال | اولین، بیشترین، کمترین و آخرین قیمت معامله |
| `avg_price` | ریال | فقط گواهی سپرده: میانگین وزنی معاملات روز، **همان قیمت پایانی بورس کالا** |
| `settlement` | ریال | قیمت تسویهٔ همین روز؛ برای گواهی سپرده با جلسهٔ بعد پر می‌شود |
| `prev_settlement` | ریال | قیمت تسویهٔ جلسهٔ قبل |
| `volume` | قرارداد یا گواهی | حجم معاملات |
| `value` | ریال | ارزش معاملات |
| `trades` | عدد | تعداد معاملات؛ گزارش آتی و اختیار آن را ندارد (`null`) |
| `open_interest`، `oi_change` | قرارداد یا گواهی | موقعیت‌های باز و تغییرش؛ برای گواهی سپرده تعداد گواهی‌های در گردش |
| `buyers`، `sellers` | نفر | تعداد خریداران و فروشندگان |
| `buy_i_volume`، `buy_n_volume`، `sell_i_volume`، `sell_n_volume` | قرارداد یا گواهی | خرید و فروش حقیقی (`_i_`) و حقوقی (`_n_`) |
| `buy_i_value`، … | ریال | ارزش همان‌ها؛ فقط آتی و اختیار |
| `source` | – | `report` یا `board`؛ جدول «هر عدد از کجا می‌آید؟» |

قراردادهای اختیار در روزهای بدون معامله هم ردیف دارند، با `volume` صفر و قیمت تسویه. ردیفی از گواهی سپرده که فقط `settlement` دارد، روزی است که پیش از شروع ثبت یا بدون اجرای روزانه گذشته و فقط قیمت تسویه‌اش از جلسهٔ بعد معلوم است.

## قیمت زنده و تغییرات درون‌روز

`GET /v1/ime/contracts/{code}/quote` در ساعات بازار آخرین وضعیت تابلو را می‌دهد (`source: "live"`): قیمت‌ها، حجم، ارزش، تعداد معاملات، موقعیت باز، بهترین خرید و فروش و دفتر سفارش در `book` به شکل `[[قیمت خرید، حجم خرید، قیمت فروش، حجم فروش]، …]`. بیرون از ساعات بازار آخرین ردیف روزانه را با `source: "daily"` برمی‌گرداند.

`GET /v1/ime/contracts/{code}/intraday?date=1405-08-24` همهٔ وضعیت‌های ثبت‌شدهٔ تابلو در آن روز را به ترتیب می‌دهد. هر وضعیت فقط وقتی ثبت می‌شود که چیزی تغییر کرده باشد؛ `ts` لحظه‌ای است که روشا تغییر را دیده، چون تابلو برای هر ردیف زمان جدا اعلام نمی‌کند.

## معاملات بازار فیزیکی را چطور بگیرم؟

`GET /v1/ime/physical` هر عرضهٔ بازار فیزیکی و صادراتی را در بازهٔ `start` تا `end` (حداکثر ۹۲ روز) برمی‌گرداند، معامله‌شده یا نشده؛ هر روز اول بیشترین ارزش.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `start` | تاریخ | لازم | اولین روز |
| `end` | تاریخ | `start` | آخرین روز |
| `q` | رشته | – | جست‌وجو در نماد، نام کالا، تولیدکننده و عرضه‌کننده؛ مثلاً `سیمان` |
| `market` | رشته | – | `main` تالارهای اصلی، `sub` تالار فرعی، `export` تالار صادراتی |
| `traded` | بولی | `false` | `true` فقط عرضه‌های معامله‌شده |
| `limit`، `offset` | عدد صحیح | `1000`، `0` | صفحه‌بندی؛ `total` تعداد همهٔ ردیف‌های منطبق است |

```bash
curl -G "https://poolick.ir/v1/ime/physical" \
  -d "start=1405-08-24" --data-urlencode "q=مس کاتد" -d "traded=true" -d "limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

| فیلد | معنا |
|---|---|
| `arzeh_pk`، `d`، `contract_type` | شناسهٔ عرضه، روز و نوع قرارداد؛ این سه با هم یکتا هستند |
| `market`، `hall` | `main`، `sub` یا `export`، و نام تالار |
| `symbol`، `goods`، `category` | نماد کالا، نام کالا، کد گروه اصلی-گروه-زیرگروه (مثل `1-3-16`) |
| `producer`، `supplier`، `broker` | تولیدکننده، عرضه‌کننده و کارگزار عرضه‌کننده |
| `settlement`، `mode`، `method` | نوع تسویه، شیوهٔ عرضه (عمده و…) و روش خرید |
| `unit`، `packaging`، `warehouse`، `delivery_date` | واحد مقدار، بسته‌بندی، محل و تاریخ تحویل |
| `offered`، `demand`، `traded` | مقدار عرضه، تقاضا و معامله، به `unit` |
| `base_price`، `max_bid` | قیمت پایهٔ عرضه و بالاترین قیمت تقاضا |
| `price_min`، `price`، `price_max` | کمترین، میانگین وزنی و بیشترین قیمت معامله |
| `value`، `currency` | ارزش معامله؛ `IRR` به ریال، `USD` به دلار |
| `fx_rate` | فقط قراردادهای دلاری صادراتی: نرخ ریالی هر دلار |

**واحد قیمت همانی است که بورس کالا منتشر می‌کند:** ریال برای هر کیلوگرم در کالاهایی که به تن عرضه می‌شوند، ریال برای هر عدد در کالاهای عددی (مثل خودرو)، و دلار برای هر تن در قراردادهای دلاری تالار صادراتی. `value` همیشه به ریال است، مگر `currency` برابر `USD` باشد.

تالار فرعی فقط مقدار منتشر می‌کند؛ قیمت و ارزش عرضه‌های آن `null` است. بورس کالا شناسهٔ عرضه را برای معاملات «مچینگ» (پر کردن تقاضای باقی‌مانده، گاهی در روزهای بعد) تکرار می‌کند؛ این معاملات با `contract_type` مثل `نقدی (مچینگ)` جدا می‌شوند.

## همین داده از راه MCP

ابزارهای `search_ime_contracts`، `get_ime_contract_history`، `get_ime_quote` و `get_ime_physical_trades` همین داده را به دستیارهای هوش مصنوعی می‌دهند؛ جدول در [ابزارهای MCP](/docs/mcp/tools/).