حقیقی و حقوقی

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

پارامترها

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

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

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

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

[
  {
    "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 است.
• ابزار MCP معادل: get_client_type_history (پیش‌فرض limit=60، سقف 500).