مستندات API قیمت طلا و ارز

معرفی

نسخهٔ 0.0.1 — تحویل JSON در همهٔ اندپوینت‌ها.

دادهٔ بازار

قیمت زندهٔ دلار، یورو و ۱۳۹ ارز دیگر + طلا، سکه و حباب‌ها؛ تازه‌سازی پیوسته.

دادهٔ رمزارز

۱۰۰ رمزارز برتر به‌همراه تغییر ۲۴س و ۷روز، مارکت‌کپ، حجم و اسپارک‌لاین.

دادهٔ تاریخی

تاریخچهٔ واقعی دلار از ۲۰۱۱ و انس جهانی از سال ۲۰۰۰ + شاخص‌های SMA/EMA.

هوش بازار

خلاصهٔ بازار، مقایسهٔ بازدهی در ۵ بازه و فید اخبار فارسی/انگلیسی.

آدرس پایهٔ همهٔ درخواست‌ها: https://ghimatrooz.com — دامنهٔ اصلی سایت قیمت روز. همهٔ اندپوینت‌ها فقط متد GET را می‌پذیرند.

شروع سریع

در کمتر از یک دقیقه اولین قیمت را بگیر:

۱. کلید بگیر

همهٔ اندپوینت‌ها برای مصرف بیرونی (سرور، ربات، اپ، سایت دیگر) کلید می‌خواهند. کلید gr_ را از پشتیبانی بگیر و در هدر x-api-key بفرست.

۲. کلید بگیر

برای نرخ بیشتر و استفادهٔ بیرونی، کلید اختصاصی gr_ بگیر (از مدیر سایت / پنل ادمین > کلیدهای API).

۳. اندپوینت مناسب را پیدا کن

از مرجع API پایین‌تر، کارتِ دقیق کاری‌ات را پیدا کن: قیمت زنده، تاریخچه، خلاصه یا اخبار.

اولین درخواست — قیمت دلار الآن:

curl -s "https://ghimatrooz.com/api/prices/iran" \
  | jq '.data[] | select(.id == "usd")'

چندزبانه (Language)

نام ارزها و طلا و سکه به هر زبان دنیا برمی‌گردد — حتی پیام خطاها به ۱۲ زبان.

پارامتر ?lang=xx

برچسب استاندارد BCP-47 — مثل ?lang=en یا ?lang=ar. هر زبان معتبری پذیرفته می‌شود؛ نام ۱۳۹ ارز ISO از پایهٔ CLDR (همان دیتای رسمی جهانی) به همان زبان ترجمه می‌شود.

تشخیص خودکار

بدون پارامتر، API از هدر Accept-Language ربات/مرورگر تو زبان را حدس می‌زند؛ اگر هیچ‌کدام نبود، فارسی (fa) پیش‌فرض است.

طلا و سکه و رمزارز

گرم طلای ۱۸، سکهٔ امامی، نیم/ربع، مثقال، تتر و انس جهانی نگاشت دستی در ۱۲ زبان دارند: fa, en, ar, tr, ru, de, fr, es, zh, hi, ur, ps

خطاهای ترجمه‌شده

خطاهای rate_limited، api_key_required و daily_quota_exceeded فیلد message را به همان زبان درخواست برمی‌گردانند.

نمونه — قیمت‌ها به زبان عربی:

curl -s "https://ghimatrooz.com/api/prices/iran?lang=ar" \
  -H "x-api-key: gr_YOUR_KEY" | jq '.data[0].name'

هر پاسخ فیلدهای lang و dir (rtl/ltr) و nameFa (نام فارسی مرجع) را هم دارد — برای ساخت اپ دوزبانه نیازی به درخواست دوم نیست.

احراز هویت و کلید

API قیمت روز کلیددار است — برای هر مصرف بیرونی کلید لازم است. کلید را همیشه در هدر x-api-key بفرست.

کلید اختصاصی gr_... — از پنل ادمین (تب «کلیدهای API») ساخته می‌شود؛ هر کلید سقف لحظه‌ای و سهمیهٔ روزانهٔ اختیاری خودش را دارد (به‌وقت تهران، ریست خودکار نیمه‌شب) و قابل غیرفعال‌کردن است — نیازی به ست‌کردن دامنه نیست؛ کلید را مستقیم در هر ربات، اپ یا سروری بگذار.
کلید مستر — مالکیت سایت، از طریق متغیر محیطی PUBLIC_API_KEY تنظیم می‌شود.
بدون کلید — فقط درخواست‌های مرورگریِ همان‌مبدأ (خودِ سایت قیمت روز). هر مصرف بیرونی بدون هدر x-api-key پاسخ 401 api_key_required می‌گیرد.

curl -s "https://ghimatrooz.com/api/prices/iran" \
  -H "x-api-key: gr_YOUR_KEY" | jq '.data | length'

هرگز کلید را در فرانت‌عمومی قرار نده؛ کلیدها روی پاسخ واترمارک می‌شوند و سوءاستفاده قابل ردیابی و غیرفعال‌کردن است.

محدودیت نرخ

الگوریتم پنجرهٔ لغزان (sliding-window) — سقف بر اساس IP یا کلید اختصاصی اعمال می‌شود.

گروه اندپوینت	سقف (در دقیقه)	کلید
قیمت‌ها (prices)	۱۲۰	`bucket=prices`
تاریخچه (history)	۶۰	`bucket=history`
خلاصه (summary)	۶۰	`bucket=summary`
اخبار (news)	۳۰	`bucket=news`
کلید اختصاصی gr_ (لحظه‌ای)	قابل تنظیم	`در پنل ادمین`
کلید اختصاصی gr_ (روزانه)	اختیاری — پیش‌فرض نامحدود	`ریست نیمه‌شب تهران`

هدرهای پاسخ: X-RateLimit-Limit و X-RateLimit-Remaining — و هنگام ۴۲۹، هدر Retry-After (ثانیه) برمی‌گردد. اگر سهمیهٔ روزانهٔ کلید تمام شود، خطای daily_quota_exceeded با هدرهای X-Daily-Limit، X-Daily-Used و Retry-After (ثانیه‌های مانده تا نیمه‌شب تهران) برمی‌گردد.

ساختار پاسخ و امضا

همهٔ پاسخ‌های موفق JSON هستند و یک بلوک _meta دارند که هم واترمارک است هم ابزار ردیابی.

قالب کلی پاسخ موفق

{
  "data": [ ... ],
  "fetchedAt": "2026-07-26T12:00:00.000Z",
  "_meta": {
    "provider": "GhimatRooz",
    "v": "0.0.1",
    "ts": 1785000000000,
    "trace": "gr-...."
  }
}

هدر X-Request-Id روی همهٔ پاسخ‌ها (حتی خطا) — برای پیگیری پشتیبانی.
هدر X-App-Signature به شکل t=...,v1=... — امضای HMAC پاسخ برای تشخیص دست‌کاری/کپی.
پاسخ خطا: {"ok": false, "error": "<code>", "requestId": "..."}

اندپوینت اختصاصی سایت (مسیرهای آسان)

مخصوص سایت خودمان — مسیرهای کوتاه و خوانا به‌فارسی؛ خروجی همیشه provider خودِ قیمت روز را دارد:

/api/dolarدلار بازار آزاد

/api/euroیورو

/api/tetrتتر

/api/talaهمهٔ اقلام طلا

/api/onsانس جهانی

/api/mesghalمثقال طلا

/api/sekeسکهٔ امامی

/api/nimsekeنیم سکه

/api/robsekeربع سکه

/api/arzهمهٔ ارزهای کشورها

/api/ramzarz۲۰ رمزارز برتر

/api/bitcoinبیت‌کوین

هر id بازار هم مستقیم کار می‌کند: /api/usd، /api/gold18، /api/emami، یا id رمزارز مثل /api/ethereum. چندزبانه‌اند: /api/dolar?lang=ar — و خروجی فیلدهای service / site (برند خودت) را هم دارد.

curl -s "https://ghimatrooz.com/api/dolar" | jq .asset

مرجع API

۹ اندپوینت عمومی + اندپوینت‌های اختصاصی آسان (/api/dolar و…) — همه فقط‌خواندنی (GET) و همه JSON:

۱۲۰/دقیقه/api/prices/iranGET

قیمت لحظه‌ای بازار ایران

لیست کامل دارایی‌های بازار ایران: ۱۶ آیتم بازار آزاد (دلار، تتر، یورو، پوند، درهم و…)، ۱۲۴ ارز جهانی، طلای ۱۸ عیار، مثقال، انس جهانی و همهٔ سکه‌ها با تغییر ۲۴ ساعته و اسپارک‌لاین.

این اندپوینت پارامتر ندارد.

نمونهٔ پاسخ (۲۰۰)

{
  "data": [
    {
      "id": "usd", "symbol": "USD", "name": "دلار آمریکا",
      "type": "fiat", "price": 193115, "change24h": 0.32,
      "unit": "toman", "sparkline": [193000, 193120, 193115],
      "live": true
    }
  ],
  "fetchedAt": "2026-07-26T12:00:00.000Z"
}

۶۰/دقیقه/api/prices/iran/historyGET

تاریخچه بازار ایران

سری زمانی واقعی برای هر دارایی ایران؛ دلار از ۲۰۱۱ تا امروز دادهٔ واقعی دارد. با indicators=true شاخص‌های SMA/EMA هم می‌گیری.

پارامترها

نام	نوع	پیش‌فرض	توضیح
`id`	`string`	`الزامی`	شناسهٔ دارایی مثل usd, gold18, emami (الگوی [a-z0-9-])
`range`	`enum`	`30d`	یکی از: 1h \| 4h \| 24h \| 7d \| 30d \| 90d \| 180d \| 365d \| 5y \| all
`indicators`	`boolean`	`false`	اگر true باشد آرایه‌های SMA/EMA هم در پاسخ می‌آید

نمونهٔ پاسخ (۲۰۰)

{
  "id": "usd", "name": "usd", "symbol": "USD", "range": "30d",
  "history": [[1750905600000, 118500], [1750992000000, 119100]],
  "meta": { "range": "30d", "points": 182, "intervalMinutes": 240,
    "confidence": 0.95, "generatedAt": "2026-07-26T12:00:00.000Z" },
  "unit": "toman", "estimated": false, "interpolated": false
}

curl -s "https://ghimatrooz.com/api/prices/iran/history?id=usd&range=365d"

۱۲۰/دقیقه/api/prices/cryptoGET

قیمت رمزارزها

۱۰۰ رمزارز برتر با قیمت دلاری، تغییر ۲۴س و ۷روز، مارکت‌کپ، حجم معاملات و اسپارک‌لاین ۷ روزه.

نمونهٔ پاسخ (۲۰۰)

{
  "data": [
    {
      "id": "bitcoin", "symbol": "BTC", "name": "Bitcoin",
      "image": "https://...", "price": 118540.2,
      "change24h": 1.84, "change7d": 4.12,
      "marketCap": 2350000000000, "volume": 42000000000,
      "sparkline": [117200, 118010, 118540]
    }
  ],
  "fetchedAt": "2026-07-26T12:00:00.000Z"
}

۶۰/دقیقه/api/prices/crypto/historyGET

تاریخچه رمزارزها

سری زمانی واقعی برای هر رمزارز — بیت‌کوین دیتای ادغام‌شده از ۲۰۱۳/۲۰۱۴ دارد؛ برای range=all کل تاریخچه برمی‌گردد.

پارامترها

نام	نوع	پیش‌فرض	توضیح
`id`	`string`	`الزامی`	شناسهٔ رمزارز مثل bitcoin, ethereum, tether
`range`	`enum`	`30d`	1h \| 4h \| 24h \| 7d \| 30d \| 90d \| 180d \| 365d \| 5y \| all
`indicators`	`boolean`	`false`	SMA/EMA در پاسخ

نمونهٔ پاسخ (۲۰۰)

{
  "id": "bitcoin", "range": "365d",
  "history": [[1672531200000, 16500], [1685577600000, 26800]],
  "meta": { "points": 365, "intervalMinutes": 1440, "confidence": 0.95 }
}

۶۰/دقیقه/api/prices/summaryGET

خلاصهٔ بازار

یک شات سریع از وضعیت کلی: قیمت BTC و ETH، نرخ تتر (تومان) و تعداد رمزارزهای فعال — کم‌حجم و مناسب هدر سایت/اپ.

نمونهٔ پاسخ (۲۰۰)

{
  "btcPrice": 118540, "btcChange24h": 1.84,
  "ethPrice": 3755, "usdtRate": 193115, "totalCryptos": 100
}

۶۰/دقیقه/api/prices/compareGET

مقایسهٔ بازدهی

بازدهی درصدی همهٔ بازارهای اصلی در پنج بازهٔ ۷روز، ۱ماه، ۳ماه، ۱سال و ۵سال؛ از روی تاریخچهٔ واقعی محلی محاسبه و ۱۰ دقیقه کش می‌شود.

نمونهٔ پاسخ (۲۰۰)

{
  "ok": true,
  "periods": ["7d", "30d", "90d", "365d", "5y"],
  "rows": [
    { "id": "gold18", "name": "گرم طلای ۱۸", "code": "GOLD18",
      "unit": "toman", "last": 6930000, "estimated": false,
      "returns": { "7d": 0.42, "30d": 3.1, "90d": 12.8, "365d": 61.5, "5y": 380.2 } }
  ],
  "updatedAt": "2026-07-26T11:55:00.000Z"
}

فقط داشبورد ادمین/api/prices/multi-sourceGET

چندمنبعی (دیباگ — فقط ادمین)

ابزار داخلی داشبورد مدیریت؛ برای عموم بسته است. مصرف عمومی از /api/prices/crypto انجام می‌شود.

پارامترها

نام	نوع	پیش‌فرض	توضیح
`symbol`	`string`	`—`	نماد رمزارز مثل BTC یا شناسه مثل bitcoin → پاسخ تجمیع چندمنبعی
`action`	`enum`	`—`	پارامتر داخلی داشبورد مدیریت

نمونهٔ پاسخ (۲۰۰)

{
  "symbol": "BTC", "price": 118540,
  "sources": [ { "name": "...", "price": 118540, "ok": true } ],
  "agreement": 0.98
}

۳۰/دقیقه/api/newsGET

اخبار بازار

تازه‌ترین خبرهای اقتصادی از فیدهای فارسی و انگلیسی؛ مرتب‌شده بر اساس زمان انتشار.

پارامترها

نام	نوع	پیش‌فرض	توضیح
`limit`	`int`	`24`	تعداد خبرها — از ۱ تا ۵۰

نمونهٔ پاسخ (۲۰۰)

{
  "items": [
    { "id": "...", "title": "تیتر خبر", "link": "https://...",
      "pubDate": "2026-07-26T10:30:00.000Z", "lang": "fa" }
  ],
  "sources": [ { "ok": true }, { "ok": true } ],
  "cachedAt": "2026-07-26T12:00:00.000Z"
}

عمومی/api/healthGET

سلامت سرویس

برای مانیتورینگ و آپ‌تایم‌چکرها — وضعیت کلی سرویس و نسخه.

نمونهٔ پاسخ (۲۰۰)

{
  "status": "ok", "version": "0.0.1",
  "timestamp": "2026-07-26T12:00:00.000Z",
  "environment": "production", "uptime": 86400.5,
  "services": { "database": "postgresql", "auth": "nextauth", "prices": "active" }
}

خرید API

مثل سایت‌های بزرگ دیتا — پلن مناسب کار خود را انتخاب کن؛ فعال‌سازی فقط با یک ایمیل انجام می‌شود.

پایه

استعلام با ایمیل

کلید اختصاصی gr_ بدون نیاز به دامنه
۱۲۰ درخواست در دقیقه
سهمیهٔ روزانهٔ سفارشی (پیش‌فرض ۵٬۰۰۰)
پشتیبانی ایمیلی

خرید با ایمیل

محبوب‌ترین

حرفه‌ای

استعلام با ایمیل

۳۰۰ درخواست در دقیقه
سهمیهٔ روزانهٔ بالا (۵۰٬۰۰۰+)
پایداری SLA + دید متادیتا
تاریخچهٔ کامل + اندیکاتورها

خرید با ایمیل

سازمانی

استعلام با ایمیل

سهمیهٔ نامحدود روزانه
هزار درخواست در دقیقه
Endpoint اختصاصی سایت شما
پشتیبانی اختصاصی + ورودی سفارشی

خرید با ایمیل

صدور کلید دستی و فوری است: یک ایمیل بده، کلید gr_ با سقف دلخواهت صادر می‌شود و جلوی چشمت در پنل فعال است. سهمیهٔ روزانه نیمه‌شب به‌وقت تهران خودکار ریست می‌شود.

برای خرید فقط به ایمیل مراجعه کنید — AmirAryayi@Proton.me تبلیغات روی سایت

کدهای خطا

خطاها همیشه با قالب استاندارد {ok:false, error, requestId} و هدر X-Request-Id برمی‌گردند:

HTTP	کد خطا	معنی و راه‌حل
400	`bad_request`	پارامتر نامعتبر — الگوی id و range را چک کن
401	`api_key_required`	برای این استفاده، کلید لازم است — هدر x-api-key را بفرست
401	`invalid_api_key`	کلید اشتباه است
401	`api_key_inactive`	کلید غیرفعال شده — با مدیر تماس بگیر
401	`domain_not_allowed`	دامنهٔ فعلی برای این کلید مجاز نیست
403	`forbidden_origin`	درخواست مرورگری از سایت بیگانه — سیاست ضدکپی
404	`not_found`	دارایی/رکورد پیدا نشد
429	`rate_limited`	از سقف نرخ گذشتی — به Retry-After احترام بگذار
429	`key_rate_limited`	سقف اختصاصی کلید خودت

بهترین روش‌ها

الگوهایی که در محصول واقعی خوب مقیاس می‌شوند:

قیمت‌ها را سمت سرور خودت کش کن (۵–۳۰ ثانیه) و مستقیم به کاربر نده — هم سریع‌تر است هم نرخ مصرف نمی‌شود.
به هدرهای Retry-After و X-RateLimit-Remaining احترام بگذار و با backoff نمایی تلاش مجدد کن.
برای چارت از one-shot درخواست تاریخچه استفاده کن، نه پولینگ قیمت زنده.
آپ‌تایم را با /api/health مانیتور کن و requestId خطاها را برای پشتیبانی نگه دار.
دادهٔ دارای estimated=true (بازه‌های خیلی دور بعضی ارزها) را در UI خودت هم علامت بزن — صداقت با کاربر.

مستندات API قیمت روز

مرجع API

قیمت لحظه‌ای بازار ایران

تاریخچه بازار ایران

قیمت رمزارزها

تاریخچه رمزارزها

خلاصهٔ بازار

مقایسهٔ بازدهی

چندمنبعی (دیباگ — فقط ادمین)

اخبار بازار

سلامت سرویس