# شروع سریع

> از ثبت‌نام تا اولین پاسخ JSON روشا در دو دقیقه؛ کلید رایگان بگیرید و با curl، پایتون یا جاوااسکریپت سابقهٔ قیمت یک نماد را بخوانید.
> Source: https://poolick.ir/docs/quickstart/

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

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

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

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

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

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

در [صفحهٔ ثبت‌نام پنل](/panel/signup/) شمارهٔ موبایل یا ایمیل خود را وارد کنید و کدی را که پیامک یا ایمیل می‌شود بزنید. حساب شما با پلن رایگان ساخته می‌شود و اولین کلید همان لحظه نمایش داده می‌شود.

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

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

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

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

```bash
export ROSHA_KEY="rosha_xxxxxxxx_your-secret"
```

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

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

**curl**

```bash
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**

```python

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**

```js
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` تازه‌ترین روز معاملاتی است.

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

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

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

شرح همهٔ فیلدها در [سابقهٔ روزانه](/docs/api/daily/) است.

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

- برای محاسبهٔ بازده، قیمت تعدیل‌شده بگیرید: `adjusted=true` را به همین درخواست اضافه کنید. شرح در [سابقهٔ روزانه](/docs/api/daily/).
- نماد را یک بار با [جست‌وجو](/docs/api/instruments/) پیدا کنید و از آن پس با `ins_code` کار کنید.
- دستیار هوش مصنوعی خود را وصل کنید: [MCP چیست و چطور وصل شوم؟](/docs/mcp/)
- داده را در دیتافریم بریزید: [پایتون و pandas](/docs/python/).
- سقف‌های پلن خود را بشناسید: [محدودیت‌ها و پلن‌ها](/docs/limits/) و [خطاها](/docs/errors/).