دادهٔ لحظه‌ای

خانوادهٔ intraday سه endpoint دارد: /quote آخرین قیمت و عمق بازار یک نماد را می‌دهد، /trades ریزمعاملات یک روز را و /bars کندل‌های درون‌روز را. هر سه به پلنی نیاز دارند که intraday داشته باشد (تا آبان ۱۴۰۵: حرفه‌ای و سازمانی)؛ در غیر این صورت پاسخ 403 plan_forbids است.

quote: آخرین قیمت یک نماد چیست؟

GET /v1/instruments/{ref}/quote در ساعات بازار snapshot زنده برمی‌گرداند ("source": "live") و خارج از ساعات بازار آخرین ردیف روزانه را ("source": "daily"). همیشه source را بررسی کنید.

پارامتر	نوع	پیش‌فرض	معنا
ref	رشته، در مسیر	–	insCode، InstrumentID یا ISIN، یا نماد فارسی دقیق

curl "https://poolick.ir/v1/instruments/46348559193224090/quote" \
  -H "Authorization: Bearer $ROSHA_KEY"

پاسخ خارج از ساعات بازار (source: daily)

این پاسخ واقعی در شب گرفته شده است. فیلدها همان فیلدهای یک ردیف سابقهٔ روزانه هستند، بدون jdate و بدون عمق بازار.

{
  "source": "daily",
  "ins_code": "46348559193224090",
  "d": "2026-11-11",
  "open": 4950.0,
  "high": 4950.0,
  "low": 4950.0,
  "close": 4950.0,
  "last": 4950.0,
  "prev_close": 4810.0,
  "volume": 1142422228.0,
  "value": 5654990028600.0,
  "trades": 9998
}

پاسخ در ساعات بازار (source: live)

snapshot زنده این فیلدها را دارد:

فیلد	نوع	واحد	معنا
source	رشته	–	live
ins_code	رشته	–	شناسهٔ نماد
ts	زمان	ISO 8601، وقت تهران	زمان snapshot
last	عدد	ریال	قیمت آخرین معامله
close	عدد	ریال	قیمت پایانی تا این لحظه
open	عدد	ریال	قیمت اولین معامله
high	عدد	ریال	بیشترین قیمت روز
low	عدد	ریال	کمترین قیمت روز
prev_close	عدد	ریال	قیمت پایانی روز قبل
volume	عدد	سهم	حجم معاملات تا این لحظه
value	عدد	ریال	ارزش معاملات تا این لحظه
trades	عدد صحیح	–	تعداد معاملات تا این لحظه
bid	عدد	ریال	بالاترین قیمت سفارش خرید
ask	عدد	ریال	پایین‌ترین قیمت سفارش فروش
book	آرایه	–	عمق بازار، یک عضو برای هر سطح
book[].level	عدد صحیح	–	شمارهٔ سطح
book[].bid_price	عدد	ریال	قیمت خرید در این سطح
book[].bid_volume	عدد	سهم	حجم خرید در این سطح
book[].bid_orders	عدد صحیح	–	تعداد سفارش خرید در این سطح
book[].ask_price	عدد	ریال	قیمت فروش در این سطح
book[].ask_volume	عدد	سهم	حجم فروش در این سطح
book[].ask_orders	عدد صحیح	–	تعداد سفارش فروش در این سطح
client_type	شیء یا null	–	ارقام خام حقیقی و حقوقی TSETMC در همان لحظه؛ اگر موجود نباشد null

quote چقدر تازه است؟

snapshot زنده تا ساعت ۱۳:۰۵ تهران هر ۳۰ ثانیه و از آن پس تا ۱۸:۰۵ هر ۲ دقیقه تازه می‌شود (صندوق‌های قابل معامله تا حدود ساعت ۱۸ معامله می‌شوند). فراخوانی بیش از این آهنگ دادهٔ تازه‌تری نمی‌دهد.

حالت‌های مرزی quote

• quote در شب: snapshot زنده پس از پایان جلسهٔ معاملاتی منقضی می‌شود. پس quote در شب همیشه source: daily است و قیمت پایانی آخرین روز معاملاتی را می‌دهد.
• تفاوت شکل دو پاسخ: پاسخ daily فیلد d دارد و ts، bid، ask، book و client_type ندارد. کد شما باید هر دو شکل را بپذیرد.
• در دسترس نبودن دادهٔ زنده: اگر snapshot زنده موقتاً در دسترس نباشد، پاسخ به source: daily برمی‌گردد و خطا نمی‌دهد.
• نماد بدون داده: اگر نماد نه snapshot زنده داشته باشد و نه ردیف روزانه، پاسخ 404 با {"detail": "no data for 32097828799138957"} است.

trades: ریزمعاملات یک روز کدام‌اند؟

GET /v1/instruments/{ref}/trades?date=<تاریخ> همهٔ ریزمعاملات (tickهای) یک روز را به ترتیب وقوع برمی‌گرداند، تا سقف ۲۰٬۰۰۰ ردیف.

پارامتر	نوع	پیش‌فرض	معنا
ref	رشته، در مسیر	–	insCode، InstrumentID یا ISIN، یا نماد فارسی دقیق
date	تاریخ، الزامی	–	روز مورد نظر؛ 2026-11-11، 20261111 یا 1405-08-20

curl "https://poolick.ir/v1/instruments/46348559193224090/trades?date=2026-11-11" \
  -H "Authorization: Bearer $ROSHA_KEY"

پاسخ (دو ردیف اول از ۹٬۹۹۸ ردیف):

[
  {"ts": "2026-11-11T09:00:43+03:30", "n_tran": 1, "price": 4950.0, "volume": 300000.0, "canceled": false},
  {"ts": "2026-11-11T09:00:43+03:30", "n_tran": 2, "price": 4950.0, "volume": 300000.0, "canceled": false}
]

فیلد	نوع	واحد	معنا
ts	زمان	ISO 8601، وقت تهران	زمان معامله
n_tran	عدد صحیح	–	شمارهٔ ردیف معامله در آن روز
price	عدد	ریال	قیمت معامله
volume	عدد	سهم	حجم معامله
canceled	بولی	–	true اگر معامله باطل شده باشد

معاملات باطل‌شده هم در پاسخ هستند و با canceled: true مشخص می‌شوند. ترتیب ردیف‌ها بر اساس ts و سپس n_tran است.

bars: چطور کندل درون‌روز بگیرم؟

GET /v1/instruments/{ref}/bars?date=<تاریخ>&minutes=<n> کندل‌های OHLCV یک روز را از روی ریزمعاملات می‌سازد. معاملات باطل‌شده در کندل‌ها حساب نمی‌شوند.

پارامتر	نوع	پیش‌فرض	معنا
ref	رشته، در مسیر	–	insCode، InstrumentID یا ISIN، یا نماد فارسی دقیق
date	تاریخ، الزامی	–	روز مورد نظر
minutes	عدد صحیح	1	طول هر کندل به دقیقه، از 1 تا 240

curl "https://poolick.ir/v1/instruments/46348559193224090/bars?date=2026-11-11&minutes=30" \
  -H "Authorization: Bearer $ROSHA_KEY"

پاسخ (سه کندل اول از هفت کندل):

[
  {"t": "2026-11-11T09:00:00+03:30", "open": 4950.0, "high": 4950.0, "low": 4950.0, "close": 4950.0, "volume": 324011903.0, "trades": 2890},
  {"t": "2026-11-11T09:30:00+03:30", "open": 4950.0, "high": 4950.0, "low": 4950.0, "close": 4950.0, "volume": 216768151.0, "trades": 1850},
  {"t": "2026-11-11T10:00:00+03:30", "open": 4950.0, "high": 4950.0, "low": 4950.0, "close": 4950.0, "volume": 102720534.0, "trades": 964}
]

فیلد	نوع	واحد	معنا
t	زمان	ISO 8601، وقت تهران	شروع کندل
open	عدد	ریال	قیمت اولین معاملهٔ کندل
high	عدد	ریال	بیشترین قیمت کندل
low	عدد	ریال	کمترین قیمت کندل
close	عدد	ریال	قیمت آخرین معاملهٔ کندل
volume	عدد	سهم	مجموع حجم
trades	عدد صحیح	–	تعداد معاملات

• مرز کندل‌ها از نیمه‌شب تهران شمرده می‌شود. کندل ۳۰ دقیقه‌ای در :00 و :30 شروع می‌شود.
• بازه‌ای که معامله‌ای در آن نبوده کندل ندارد؛ کندل خالی ساخته نمی‌شود.
• close کندل قیمت آخرین معاملهٔ آن بازه است، نه قیمت پایانی رسمی روز.
• minutes بیرون از بازهٔ ۱ تا ۲۴۰ خطای 422 می‌گیرد.

پاسخ خالی در trades و bars یعنی چه؟

پاسخ خالی [] یعنی ریزمعاملات آن روز در روشا ذخیره نشده است، نه اینکه نماد معامله نشده است. ریزمعاملات فقط برای روزهایی موجود است که در پایان همان روز دریافت یا بعداً بازیابی شده‌اند.

• برای اینکه بدانید نماد در آن روز معامله شده یا نه، سابقهٔ روزانه را ببینید.
• اگر به ریزمعاملات یک بازهٔ مشخص نیاز دارید، پیش از شروع پروژه با پشتیبانی هماهنگ کنید.
• ریزمعاملات هر روز با دادهٔ پایان روز، ساعت ۱۸:۱۵ تهران، ذخیره می‌شود. این دو endpoint جریان زندهٔ معاملات نیستند.

ابزارهای MCP معادل

get_quote معادل /quote و get_intraday_bars معادل /bars است (پیش‌فرض minutes=5، حداکثر ۵۰۰ کندل). برای ریزمعاملات ابزار MCP وجود ندارد.