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

> سه endpoint درون‌روز روشا؛ quote برای آخرین قیمت و عمق بازار، trades برای ریزمعاملات یک روز و bars برای کندل‌های OHLCV از ۱ تا ۲۴۰ دقیقه.
> Source: https://poolick.ir/docs/api/intraday/

خانوادهٔ `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، یا نماد فارسی دقیق |

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

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

این پاسخ واقعی در شب گرفته شده است. فیلدها همان فیلدهای یک ردیف [سابقهٔ روزانه](/docs/api/daily/) هستند، بدون `jdate` و بدون عمق بازار.

```json
{
  "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` |

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

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

```json
[
  {"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` |

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

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

```json
[
  {"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 یعنی چه؟

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

- برای اینکه بدانید نماد در آن روز معامله شده یا نه، [سابقهٔ روزانه](/docs/api/daily/) را ببینید.
- اگر به ریزمعاملات یک بازهٔ مشخص نیاز دارید، پیش از شروع پروژه با [پشتیبانی](/contact/) هماهنگ کنید.
- ریزمعاملات هر روز با دادهٔ پایان روز، ساعت ۱۸:۱۵ تهران، ذخیره می‌شود. این دو endpoint جریان زندهٔ معاملات نیستند.

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

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