بورس کالا

روشا از بورس کالای ایران (ime.co.ir) فقط داده‌هایی را می‌گیرد که در TSETMC نیست: گواهی سپرده کالایی، قراردادهای اختیار معامله و آتی، و معاملات بازار فیزیکی و صادراتی. گواهی‌های کالایی مثل زعفران، صندوق‌های کالایی مثل «عیار» و قراردادهای سلف در TSETMC نماد دارند؛ آن‌ها را از /v1/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	ردیف‌هایی که از ابتدای فهرست رد می‌شود

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 روز آخر بازه را نگه می‌دارد.

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

{
  "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 تعداد همهٔ ردیف‌های منطبق است

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.