سری زمانی نرخ یک ارز، در دو دقت:

درون‌روزی (interval کمتر از یک روز): از ثبت خود نِت اَرز که هر تغییر نرخ دلار را نگه می‌دارد، از ۲۴ تیر ۱۴۰۵ به بعد. هر نقطه با برابری همان روز آن ارز قیمت می‌خورد، نه برابری امروز.
روزانه و درشت‌تر (interval یک روز یا بیشتر): از آرشیو نرخ ارز، نرخ پایانی بازار آزاد در هر روز کاری. دلار از ۱۳۶۰ (تا ۱۳۷۹ میانگین سالانه یا ماهانه)، یورو و پوند و درهم از ۱۳۹۱ و بیشتر ارزها از ۱۳۹۳؛ سال‌های پیش از آن، برای بیشتر ارزها «برآورد» از روی دلار است.

GET /api/fx/v1/history/{code} رایگان + پرو

پارامتر	توضیح
`range`	`1h`، `24h` (پیش‌فرض)، `7d`، `30d`، `90d`، `1y`، `3y`، `5y`، `10y` یا `all` (از اولین روز آرشیو همان ارز). با `from` نادیده گرفته می‌شود.
`from` / `to`	بازهٔ دلخواه (ISO 8601 یا Unix timestamp). `to` پیش‌فرض «الان».
`interval`	بازهٔ نمونه‌برداری: `5m`، `15m`، `30m`، `1h`، `4h`، `1d`، `1w`، `1mo` (۳۰ روز) یا عدد (دقیقه). پیش‌فرض بر اساس بازه: ۵ دقیقه برای ۱ ساعت، ۱۵ دقیقه برای ۲۴ ساعت، ۱ ساعت برای ۷ روز، ۴ ساعت برای ۳۰ روز، و بعد از آن روزانه، هفتگی یا ماهانه تا تعداد نقاط از سقف نگذرد. `interval` کمتر از یک روز برای پیش از شروع ثبت درون‌روزی → `400 archive_is_daily`.
`format`	`json` (پیش‌فرض) یا `csv`.

cURL

curl "https://netarz.ir/api/fx/v1/history/USD?range=7d&interval=1h" \
  -H "Authorization: Bearer $NETARZ_FX_KEY"

پاسخ

{
  "data": [
    { "t": "2026-08-29T11:00:00+03:30", "v": 101200 },
    { "t": "2026-08-29T12:00:00+03:30", "v": 101200 },
    { "t": "2026-08-29T13:00:00+03:30", "v": 101500 },
    "…",
    { "t": "2026-09-05T10:00:00+03:30", "v": 102400 }
  ],
  "meta": {
    "code": "USD", "quote_currency": "IRT", "unit": 1,
    "from": "2026-08-29T10:20:00+03:30", "to": "2026-09-05T10:20:00+03:30",
    "interval_minutes": 60, "points": 168, "plan": "pro", "delayed_minutes": 0,
    "note": "each point carries the last known market mid at its timestamp; values are Toman per quote unit."
  }
}

منطق نقاط

هر نقطه «آخرین نرخ شناخته‌شده در آن لحظه» است. یعنی اگر بازار یک روز آرام بوده، یک خط صاف می‌گیرید؛ نه گپ، نه عدد اختراعی. اولین نقطه هم با آخرین نرخ قبل از شروع بازه پر می‌شود تا نمودار از ابتدا مقدار داشته باشد. اگر برای بازه‌ای اصلاً داده‌ای نباشد (قبل از شروع آرشیو)، آن نقاط حذف می‌شوند. در دقت روزانه t خودِ روز تهران است (2018-09-25) و meta.resolution می‌گوید پاسخ روزانه است یا درون‌روزی.

چه کسی به تاریخچه دسترسی دارد

پرو: کل آرشیو، دلار از ۱۳۶۰، خروجی CSV، آرشیو روزانه و endpointهای OHLC، آمار و snapshot.
رایگان: تاریخچه ندارد. درخواست خارج از طرح → 402 pro_required.
سقف نقاط هر پاسخ ۲,۰۰۰ است؛ برای بازهٔ بلند، interval بزرگ‌تر بدهید وگرنه 400 too_many_points می‌گیرید.

بازهٔ دلخواه و CSV

from / to

# بازهٔ دلخواه با from/to (ISO 8601 یا Unix timestamp)
curl "https://netarz.ir/api/fx/v1/history/EUR?from=2026-08-01T00:00:00Z&to=2026-08-31T23:59:59Z&interval=1d" \
  -H "Authorization: Bearer $NETARZ_FX_KEY"

CSV

curl "https://netarz.ir/api/fx/v1/history/USD?range=30d&interval=1d&format=csv" \
  -H "Authorization: Bearer $NETARZ_FX_KEY" -o usd-30d.csv

# time,USD_IRT
# 2026-08-07T10:20:00+03:30,99800
# 2026-08-08T10:20:00+03:30,100100
# …

آرشیو روزانه

خودِ آرشیو، روزبه‌روز: برای هر روز کاری یک کندل (بازگشایی، بیشترین، کمترین، پایانی) با تاریخ میلادی و شمسی. فقط در طرح پرو.

GET /api/fx/v1/archive/{code} رایگان + پرو

پارامتر	توضیح
`date`	نرخ یک روز. اگر آن روز تعطیل بوده، آخرین روز کاری پیش از آن برمی‌گردد و `exact` برابر `false` است.
`from` / `to`	بازهٔ روزها. پیش‌فرض: یک سال تا آخرین روز آرشیو. در هر پاسخ حداکثر ۲۰,۰۰۰ ردیف (کل آرشیو دلار حدود ۱۳ هزار ردیف است).
`format`	`json` (پیش‌فرض) یا `csv`.

تاریخ‌ها را به‌صورت YYYY-MM-DD بدهید، میلادی (2018-09-25) یا شمسی (1397-07-03 یا 1397/07/03)؛ هر سالی پیش از ۱۷۰۰ شمسی خوانده می‌شود.

cURL

# نرخ یک روز (تاریخ شمسی یا میلادی)
curl "https://netarz.ir/api/fx/v1/archive/USD?date=1397-07-03" \
  -H "Authorization: Bearer $NETARZ_FX_KEY"

# همهٔ روزهای یک بازه، برای اکسل
curl "https://netarz.ir/api/fx/v1/archive/EUR?from=1399-01-01&to=1399-12-30&format=csv" \
  -H "Authorization: Bearer $NETARZ_FX_KEY" -o eur-1399.csv

پاسخ

{
  "data": {
    "code": "USD", "quote_currency": "IRT", "unit": 1,
    "requested": "2018-09-25", "exact": true,
    "date": "2018-09-25", "jdate": "1397-07-03",
    "open": 19010, "high": 19350, "low": 16830, "close": 18670,
    "source": "market", "resolution": "daily"
  }
}

فیلد	معنا
`source`	`market`: نرخ پایانی بازار آزاد تهران. `derived`: برای سال‌هایی که دادهٔ بازار آن ارز نداریم، دلار همان روز تقسیم بر برابری رسمی آن ارز (نرخ‌های مرجع بانک مرکزی اروپا از ۱۹۹۹، یا نرخ ثابت ارزهای وابسته به دلار از روز تثبیت).
`resolution`	`daily`، یا برای دلارِ سال‌های ۱۳۶۰ تا ۱۳۶۳ `yearly` (میانگین سالانه) و ۱۳۶۴ تا ۱۳۷۹ `monthly` (میانگین ماهانه).
`open` … `close`	تومان برای واحد مظنهٔ همان ارز (`unit`؛ مثلاً هر ۱۰۰ دینار عراق).

نرخ امروزِ /rates قیمت لحظه‌ای تتر است و آرشیو نرخ پایانی بازار آزاد؛ این دو معمولاً کمتر از یک درصد با هم فرق دارند. اولین روز آرشیو هر ارز در فیلد archive_from از GET /currencies آمده است.

رسم نمودار

Chart.js

// Chart.js — یک نمودار خطی ساده
const { data } = await (await fetch("https://netarz.ir/api/fx/v1/history/USD?range=30d&interval=4h", {
  headers: { Authorization: "Bearer fx-ntz-v1-..." },
})).json();

new Chart(document.getElementById("usd"), {
  type: "line",
  data: { labels: data.map(p => p.t), datasets: [{ label: "USD/IRT", data: data.map(p => p.v), tension: 0.3 }] },
  options: { scales: { x: { type: "time" } } },
});