زرنرخ — API

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

قیمت لحظه‌ای سکه، طلا، نقره و ارز — به‌صورت REST و WebSocket

برای استفاده به یک کلید دسترسی نیاز دارید. کلید را از مدیر سیستم بگیرید و در هدر X-API-KEY بفرستید. تمام درخواست‌ها روی https://api.zarnerkh.ir است.

احراز هویت

کلید را در هدر هر درخواست قرار دهید:

X-API-KEY: کلید‌شما

برای WebSocket که امکان ارسال هدر نیست، کلید را در پارامتر api_key بدهید.

محدودیت‌ها

اندپوینت‌ها

متدمسیرتوضیح
GET/v1/pricesهمه‌ی قیمت‌ها، گروه‌بندی‌شده
GET/v1/prices/:groupیک گروه خاص
GET/v1/healthسلامت سرویس (بدون کلید)
WS/wsپوش زنده‌ی تغییرات

گروه‌های موجود: arz — ارزsekke — سکه abshodeh — آبشدهparsian — پارسیان noghre — نقره

نمونه درخواست

cURL

curl -H "X-API-KEY: کلید‌شما" \
  https://api.zarnerkh.ir/v1/prices

JavaScript (fetch)

const res = await fetch('https://api.zarnerkh.ir/v1/prices', {
  headers: { 'X-API-KEY': 'کلید‌شما' }
});
const data = await res.json();
console.log(data.groups.sekke.items);

WebSocket (زنده)

const ws = new WebSocket(
  'wss://api.zarnerkh.ir/ws?api_key=کلید‌شما'
);
const prices = new Map();
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'snapshot') {
    for (const g of Object.values(msg.data.groups))
      for (const it of g.items) prices.set(it.id, it);
  } else if (msg.type === 'update') {
    for (const it of msg.items) prices.set(it.id, it);
  }
  // هر آیتم دارای change / dir / changed_at برای فلش‌زدن است
};

ساختار خروجی

{
  "success": true,
  "updated_at": "2026-07-02T14:48:38+03:30",
  "unit": "toman",
  "products_count": 39,
  "stale": false,
  "groups": {
    "sekke": {
      "key": "sekke", "label": "سکه",
      "items": [{
        "id": 7, "code": "11", "name": "سکه تمام امامی 86",
        "buy": 176800000, "sell": 175900000, "base": 176350000,
        "buy_enabled": true, "sell_enabled": false,
        "change": 450000, "change_percent": 0.26, "dir": "up",
        "updated_at": "2026-07-02T14:48:01+03:30",
        "changed_at": "2026-07-02T14:48:38+03:30"
      }]
    }
  }
}
فیلدتوضیح
buy / sellقیمت خرید / فروش (تومان، عدد خام)
baseقیمت پایه
change / change_percentتغییر قیمت خرید نسبت به آخرین مقدار
dirup / down / same
changed_atزمان آخرین حرکت قیمت (برای فلش‌زدن)
staleدر صورت true داده ممکن است کمی کهنه باشد

کدهای وضعیت

کدمعنی
200موفق
401کلید ارسال نشده یا نامعتبر
403کلید غیرفعال، منقضی، یا IP غیرمجاز
429عبور از سقف درخواست (کمی صبر کنید)