شروع سریع

برای اولین پاسخ سه کار لازم است: کلید رایگان بگیرید، آن را در ROSHA_KEY بگذارید و یک درخواست GET بفرستید. پلن رایگان سابقهٔ روزانه و MCP را دارد و کارت بانکی نمی‌خواهد.

پیش از ثبت‌نام: یک پاسخ واقعی ببینید

endpoint نمایشی روشا بدون کلید جواب می‌دهد. این درخواست پنج روز معاملاتی اخیر فولاد را برمی‌گرداند:

curl "https://poolick.ir/demo/v1/instruments/IRO1FOLD0001/daily?limit=5"

endpoint نمایشی فقط دادهٔ پایان روز دارد، حداکثر ۳۰ ردیف برمی‌گرداند و به ۳۰ درخواست در دقیقه برای هر IP محدود است. برای کار واقعی کلید بگیرید.

۱. کلید رایگان بگیرید

در صفحهٔ ثبت‌نام پنل شمارهٔ موبایل یا ایمیل خود را وارد کنید و کدی را که پیامک یا ایمیل می‌شود بزنید. حساب شما با پلن رایگان ساخته می‌شود و اولین کلید همان لحظه نمایش داده می‌شود.

احتیاط

کلید کامل فقط یک بار نمایش داده می‌شود. همان لحظه آن را در جای امنی ذخیره کنید. اگر گم شد، در پنل کلید را بچرخانید تا کلید تازه بگیرید.

کلید این شکل را دارد: rosha_xxxxxxxx_your-secret.

۲. کلید را در ROSHA_KEY بگذارید

همهٔ نمونه‌های این مستندات کلید را از متغیر محیطی ROSHA_KEY می‌خوانند تا کلید در کد شما نماند.

export ROSHA_KEY="rosha_xxxxxxxx_your-secret"

۳. اولین درخواست را بفرستید

این درخواست پنج روز معاملاتی اخیر نماد فولاد را می‌گیرد. نماد فارسی در نشانی باید URL-encode شود؛ کتابخانه‌های پایتون و جاوااسکریپت این کار را خودشان انجام می‌دهند.

curl

curl "https://poolick.ir/v1/instruments/%D9%81%D9%88%D9%84%D8%A7%D8%AF/daily?limit=5" \
  -H "Authorization: Bearer $ROSHA_KEY"

Python

import os
import time

import requests

BASE = "https://poolick.ir"
HEADERS = {"Authorization": f"Bearer {os.environ['ROSHA_KEY']}"}


def get(path, **kwargs):
    """GET with one retry on 429, waiting as long as Retry-After says."""
    for _ in range(2):
        r = requests.get(BASE + path, headers=HEADERS, timeout=30, **kwargs)
        if r.status_code != 429:
            break
        time.sleep(int(r.headers.get("Retry-After", "1")))
    r.raise_for_status()
    return r.json()


data = get(
    "/v1/instruments/فولاد/daily",
    params={"limit": 5},
)
print(data["rows"][-1])

JavaScript

const BASE = "https://poolick.ir";

async function get(path) {
  for (let attempt = 0; attempt < 2; attempt++) {
    const res = await fetch(BASE + path, {
      headers: { Authorization: `Bearer ${process.env.ROSHA_KEY}` },
    });
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, 1000 * Number(res.headers.get("Retry-After") ?? 1)));
      continue;
    }
    if (!res.ok) throw new Error(`${res.status} ${(await res.json()).detail}`);
    return res.json();
  }
  throw new Error("rate limited");
}

const data = await get("/v1/instruments/فولاد/daily?limit=5");
console.log(data.rows.at(-1));

نمونهٔ پایتون به requests نیاز دارد (pip install requests). نمونهٔ جاوااسکریپت با Node.js 18 یا بالاتر، در یک فایل .mjs اجرا می‌شود.

پاسخ را چطور بخوانم؟

پاسخ یک شیء JSON است که ردیف‌های روزانه را در rows، از قدیم به جدید، دارد. آخرین عضو rows تازه‌ترین روز معاملاتی است.

{
  "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"
    }
  ]
}

چهار نکته که از همین اول به کارتان می‌آید:

• قیمت‌ها و ارزش معاملات به ریال است، نه تومان.
• close قیمت پایانی است و last قیمت آخرین معامله.
• ins_code رشته است. آن را به عدد تبدیل نکنید.
• limit=5 یعنی پنج ردیف آخر بازه. ترتیب ردیف‌ها همیشه از قدیم به جدید است.

شرح همهٔ فیلدها در سابقهٔ روزانه است.

گام بعدی چیست؟

• برای محاسبهٔ بازده، قیمت تعدیل‌شده بگیرید: adjusted=true را به همین درخواست اضافه کنید. شرح در سابقهٔ روزانه.
• نماد را یک بار با جست‌وجو پیدا کنید و از آن پس با ins_code کار کنید.
• دستیار هوش مصنوعی خود را وصل کنید: MCP چیست و چطور وصل شوم؟
• داده را در دیتافریم بریزید: پایتون و pandas.
• سقف‌های پلن خود را بشناسید: محدودیت‌ها و پلن‌ها و خطاها.