# حقیقی و حقوقی

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

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

## پارامترها

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

## چطور آمار حقیقی و حقوقی یک نماد را بگیرم؟

```bash
curl "https://poolick.ir/v1/instruments/46348559193224090/client-type?limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

پاسخ یک آرایه است، از قدیم به جدید:

```json
[
  {
    "d": "2026-11-11",
    "buy_i_volume": 897812127.0,
    "buy_n_volume": 244610101.0,
    "buy_i_value": 4444170028650.0,
    "buy_n_value": 1210819999950.0,
    "buy_i_count": 1279,
    "buy_n_count": 78,
    "sell_i_volume": 157756362.0,
    "sell_n_volume": 984665866.0,
    "sell_i_value": 780893991900.0,
    "sell_n_value": 4874096036700.0,
    "sell_i_count": 1866,
    "sell_n_count": 19
  }
]
```

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

در نام فیلدها `_i_` یعنی حقیقی (individual) و `_n_` یعنی حقوقی.

| فیلد | نوع | واحد | معنا |
|---|---|---|---|
| `d` | تاریخ | میلادی ISO | روز معاملاتی |
| `buy_i_volume` | عدد | سهم | حجم خرید حقیقی |
| `buy_n_volume` | عدد | سهم | حجم خرید حقوقی |
| `buy_i_value` | عدد | ریال | ارزش خرید حقیقی |
| `buy_n_value` | عدد | ریال | ارزش خرید حقوقی |
| `buy_i_count` | عدد صحیح | – | تعداد خریداران حقیقی |
| `buy_n_count` | عدد صحیح | – | تعداد خریداران حقوقی |
| `sell_i_volume` | عدد | سهم | حجم فروش حقیقی |
| `sell_n_volume` | عدد | سهم | حجم فروش حقوقی |
| `sell_i_value` | عدد | ریال | ارزش فروش حقیقی |
| `sell_n_value` | عدد | ریال | ارزش فروش حقوقی |
| `sell_i_count` | عدد صحیح | – | تعداد فروشندگان حقیقی |
| `sell_n_count` | عدد صحیح | – | تعداد فروشندگان حقوقی |

## چطور ورود پول حقیقی و سرانهٔ خرید را حساب کنم؟

این دو عدد در پاسخ نیستند و از فیلدهای بالا به دست می‌آیند:

| شاخص | فرمول |
|---|---|
| ورود پول حقیقی در یک روز (ریال) | `buy_i_value − sell_i_value` |
| سرانهٔ خرید حقیقی (ریال) | `buy_i_value ÷ buy_i_count` |
| سرانهٔ فروش حقیقی (ریال) | `sell_i_value ÷ sell_i_count` |

در نمونهٔ بالا ورود پول حقیقی `4444170028650 − 780893991900 = 3663276036750` ریال است.

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

- **شکل پاسخ:** این endpoint آرایهٔ ساده برمی‌گرداند، نه شیئی با `rows`. فیلدهای `ins_code` و `ticker` در آن نیست.
- **بازهٔ خالی:** اگر در بازه ردیفی نباشد، پاسخ `[]` با وضعیت `200` است.
- **زمان تازه‌شدن:** با دادهٔ پایان روز، ساعت ۱۸:۱۵ تهران، شنبه تا چهارشنبه.
- **آمار همان لحظه:** در ساعات بازار، آمار حقیقی و حقوقی لحظه‌ای در فیلد `client_type` پاسخ [`/quote`](/docs/api/intraday/) است.
- **ابزار MCP معادل:** `get_client_type_history` (پیش‌فرض `limit=60`، سقف `500`).