# سابقهٔ روزانه

> سابقهٔ روزانهٔ قیمت، حجم و ارزش معاملات هر نماد بورس و فرابورس در API روشا، خام یا تعدیل‌شده؛ پارامترها، نمونهٔ پاسخ و شرح فیلدها.
> Source: https://poolick.ir/docs/api/daily/

`GET /v1/instruments/{ref}/daily` برای هر روز معاملاتی یک ردیف برمی‌گرداند: قیمت باز، بیشترین، کمترین، پایانی، آخرین معامله، حجم، ارزش و تعداد معاملات. با `adjusted=true` قیمت‌ها بابت افزایش سرمایه و سود نقدی تعدیل می‌شوند. این endpoint در خانوادهٔ `history` است.

## پارامترها

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `ref` | رشته، در مسیر | – | `insCode`، InstrumentID یا ISIN، یا نماد فارسی دقیق |
| `start` | تاریخ | بدون حد | اولین روز بازه (خود آن روز هم می‌آید) |
| `end` | تاریخ | بدون حد | آخرین روز بازه (خود آن روز هم می‌آید) |
| `adjusted` | بولی | `false` | `true` یعنی قیمت‌های تعدیل‌شده |
| `limit` | عدد صحیح | `1000` | N ردیف آخر بازه را نگه می‌دارد. سقف `5000`. |

تاریخ‌ها سه قالب را می‌پذیرند: `2026-11-11`، `20261111` و شمسی `1405-08-20`.

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

`ref` را بدهید و با `limit` یا `start` و `end` بازه را مشخص کنید. این درخواست دو روز معاملاتی آخر فولاد را می‌گیرد:

```bash
curl "https://poolick.ir/v1/instruments/IRO1FOLD0001/daily?limit=2" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

پاسخ:

```json
{
  "ins_code": "46348559193224090",
  "ticker": "فولاد",
  "adjusted": false,
  "rows": [
    {
      "d": "2026-11-10",
      "open": 4810.0,
      "high": 4810.0,
      "low": 4810.0,
      "close": 4810.0,
      "last": 4810.0,
      "prev_close": 4670.0,
      "volume": 1031669812.0,
      "value": 4962331795720.0,
      "trades": 7941,
      "jdate": "1405-08-19"
    },
    {
      "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,
      "jdate": "1405-08-20"
    }
  ]
}
```

## فیلدهای پاسخ

| فیلد | نوع | واحد | معنا |
|---|---|---|---|
| `ins_code` | رشته | – | شناسهٔ نمادی که `ref` به آن رسید |
| `ticker` | رشته | – | نماد فارسی |
| `adjusted` | بولی | – | همان مقداری که فرستاده‌اید |
| `rows` | آرایه | – | ردیف‌های روزانه، از قدیم به جدید |
| `rows[].d` | تاریخ | میلادی ISO | روز معاملاتی |
| `rows[].open` | عدد یا `null` | ریال | قیمت اولین معامله |
| `rows[].high` | عدد یا `null` | ریال | بیشترین قیمت روز |
| `rows[].low` | عدد یا `null` | ریال | کمترین قیمت روز |
| `rows[].close` | عدد | ریال | قیمت پایانی رسمی |
| `rows[].last` | عدد | ریال | قیمت آخرین معامله |
| `rows[].prev_close` | عدد | ریال | قیمت پایانی روز قبل |
| `rows[].volume` | عدد | سهم | حجم معاملات |
| `rows[].value` | عدد | ریال | ارزش معاملات |
| `rows[].trades` | عدد صحیح | – | تعداد معاملات |
| `rows[].jdate` | رشته | شمسی | همان روز به تاریخ شمسی، مثل `1405-08-20` |

## چطور سابقهٔ قیمت تعدیل‌شده را بگیرم؟

`adjusted=true` را اضافه کنید. قیمت‌های پیش از هر افزایش سرمایه یا تقسیم سود با رویدادهای تعدیل TSETMC به عقب تعدیل می‌شوند تا سری قیمت پیوسته بماند.

```bash
curl "https://poolick.ir/v1/instruments/46348559193224090/daily?end=2014-12-31&limit=2&adjusted=true" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
{
  "ins_code": "46348559193224090",
  "ticker": "فولاد",
  "adjusted": true,
  "rows": [
    {"d": "2014-12-30", "open": 400.29, "high": 403.95, "low": 393.16, "close": 400.47, "last": 400.29, "prev_close": 400.47, "volume": 2086866.0, "value": 4574660105.0, "trades": 281, "jdate": "1393-10-09"},
    {"d": "2014-12-31", "open": 400.47, "high": 403.95, "low": 392.98, "close": 400.29, "last": 392.98, "prev_close": 400.47, "volume": 1834372.0, "value": 4010608933.0, "trades": 317, "jdate": "1393-10-10"}
  ]
}
```

همین دو روز بدون تعدیل (`adjusted=false`) قیمت پایانی `2191.0` و `2190.0` دارند. حجم و ارزش در هر دو پاسخ یکی است.

قاعده‌های تعدیل:

- ضریب هر رویداد، نسبت قیمت تعدیل‌شده به تعدیل‌نشدهٔ همان رویداد است. فهرست رویدادها در [`/adjustments`](/docs/api/adjustments/) است.
- هر رویداد روزهایی را تغییر می‌دهد که هنوز بر مبنای قیمت قدیم‌اند: همهٔ روزهای **پیش از** تاریخ رویداد (D)، و خودِ روز D اگر نماد در آن روز متوقف بوده و هنوز قیمت قدیم را نشان می‌دهد.
- نشانهٔ روز D: اگر `prev_close` خام روز D با `close_adjusted` رویداد برابر باشد (با اختلاف حداکثر ۰٫۵ ریال)، روز D از قیمت جدید شروع شده و این رویداد آن را تغییر نمی‌دهد؛ وگرنه روز D هم تعدیل می‌شود. در داده‌های TSETMC تا سال ۲۰۱۹ حالت اول و از ۲۰۲۰ حالت دوم رایج است.
- ضریب‌ها روی هم ضرب می‌شوند: قیمت یک روز در ضریب همهٔ رویدادهایی ضرب می‌شود که آن روز را تغییر می‌دهند.
- فیلدهای `open`، `high`، `low`، `close`، `last` و `prev_close` تعدیل و تا دو رقم اعشار گرد می‌شوند.
- `volume`، `value` و `trades` تعدیل نمی‌شوند.

:::note
با ثبت هر رویداد تعدیل تازه، قیمت تعدیل‌شدهٔ همهٔ روزهای پیش از آن عوض می‌شود. اگر قیمت تعدیل‌شده را ذخیره می‌کنید، پس از هر رویداد تازه کل سابقه را دوباره بگیرید. راهکار در [همگام‌سازی روزانه](/docs/guides/daily-sync/) است.
:::

## نکته‌ها و حالت‌های مرزی

- **`close` با `last` فرق دارد.** `close` قیمت پایانی رسمی و `last` قیمت آخرین معامله است. این دو لزوماً برابر نیستند.
- **روز بدون معامله:** در روزهایی که نماد معامله نشده، `open`، `high` و `low` برابر `null` است. در سابقهٔ فولاد، نمونه‌اش `2009-06-15` است.
- **پرش در سابقهٔ خام:** سابقهٔ تعدیل‌نشده در روز افزایش سرمایه یا تقسیم سود پرش قیمت دارد. برای محاسبهٔ بازده و تحلیل تکنیکال `adjusted=true` بگیرید.
- **آخرین روز:** `?limit=1` تازه‌ترین روز را می‌دهد. دادهٔ روزانه ساعت ۱۸:۱۵ تهران، شنبه تا چهارشنبه، تازه می‌شود و ارقام آخرین روز ممکن است تا اجرای بعدی اصلاح شود. شرح در [به‌روزرسانی داده‌ها](/docs/freshness/).
- **بازهٔ خالی:** اگر در بازه روز معاملاتی نباشد، `rows` آرایهٔ خالی است و وضعیت `200`.
- **شاخص‌ها:** برای شاخص این endpoint ردیفی ندارد (`rows` خالی). از [`/v1/indices/{ref}/daily`](/docs/api/indices/) استفاده کنید.
- **بیش از ۵٬۰۰۰ ردیف:** با تاریخ صفحه‌بندی کنید؛ روش در [قراردادها](/docs/conventions/) و کد در [پایتون و pandas](/docs/python/).
- **ابزار MCP معادل:** `get_daily_history` (پیش‌فرض `limit=120`، سقف `500`).