سرور هر ۲ ثانیه یک‌بار قیمت‌ها را از منبع می‌خواند و در حافظه کش می‌کند. کلاینت‌های شما به‌جای تماس مستقیم با منبع، به این سرویس وصل می‌شوند و با یک کلید دسترسی (که در همین پنل می‌سازید) داده می‌گیرند. مزایا:

• کلیدِ منبعِ اصلی هرگز فاش نمی‌شود.
• محدودیت نرخِ منبع رعایت می‌شود (هرچند کلاینت وصل شوند، فشار ثابت است).
• برای هر کلاینت کلید جدا، با محدودیت و انقضای مستقل، و لاگ کامل.

[منبع اصلی] ──poll هر ۲ثانیه──▶ [کش + محاسبهٔ change] ──┬─▶ REST  /v1/prices
        (کلید مخفی)                                       └─▶ WS    /ws (پوش زنده)

1. به تب «کلیدهای دسترسی» بروید و روی «+ کلید جدید» بزنید؛ یک نام برای کلاینت بگذارید و کلید ساخته می‌شود (با zk_ شروع می‌شود).
2. کلید را کپی کنید (روی خودِ کلید در جدول کلیک کنید).
3. در برنامهٔ کلاینت، درخواست بزنید و کلید را در هدر X-API-KEY بفرستید:

curl -H "X-API-KEY: zk_YOUR_KEY" \
  https://api.zarnerkh.ir/v1/prices

هر کلید برای یک کلاینت (سایت، اپ، ربات…) ساخته می‌شود و این تنظیمات را دارد:

• نام کلاینت: فقط برای شناسایی خودتان.
• وضعیت (فعال/غیرفعال): با یک کلیک می‌توانید کلید را موقتاً ببندید بدون حذف.
• محدودیت در دقیقه: سقف تعداد درخواست هر دقیقه برای آن کلید (مثلاً ۱۲۰). بیشتر از این → خطای ۴۲۹.
• انقضا: با تقویم شمسی یک تاریخ انتخاب کنید؛ بعد از آن کلید خودکار بی‌اثر می‌شود. خالی = بدون انقضا.
• IP مجاز: اگر پر کنید، فقط از همان IPها کلید کار می‌کند (چند IP را با کاما جدا کنید). خالی = همه‌جا.

حذف کلید فوری و برگشت‌ناپذیر است؛ برای توقف موقت، بهتر است «غیرفعال» کنید.

روی همهٔ درخواست‌ها (به‌جز health) هدر X-API-KEY لازم است (یا پارامتر ?api_key=). واحد قیمت‌ها تومان است. CORS باز است (از مرورگر هم قابل استفاده).

نمونهٔ خروجی هر آیتم قیمت:

{
  "name": "دلار آمریکا آبی نقد",
  "group": "arz",
  "buy": 176500,          // قیمت خرید
  "sell": 174000,         // قیمت فروش
  "base": 175500,         // میانگین/مبنا
  "change": 500,          // تغییر نسبت به قبل
  "change_percent": 0.28,
  "dir": "up",            // up | down | same
  "updated_at": "2026-07-03T21:41:24+03:30"
}

نمونهٔ استفاده در جاوااسکریپت:

const r = await fetch('https://api.zarnerkh.ir/v1/prices/arz', {
  headers: { 'X-API-KEY': 'zk_YOUR_KEY' }
});
const data = await r.json();
console.log(data.group.items);

برای به‌روزرسانی لحظه‌ای (بدون نیاز به درخواست مکرر)، به WebSocket وصل شوید. کلید در query می‌آید. اول یک پیام snapshot (کل داده) می‌گیرید، سپس فقط updateهای تغییرکرده.

const ws = new WebSocket('wss://api.zarnerkh.ir/ws?api_key=zk_YOUR_KEY');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'snapshot') { /* داده اولیه */ }
  if (msg.type === 'update')   { /* تغییرات زنده */ }
};

برای سایت‌هایی که با اسکیمای قدیمی کار می‌کنند (مثل zarnerkh.ir) این دو مسیر خروجیِ مسطحِ سازگار می‌دهند:

• GET /legacy/prices — اسنپ‌شات مسطح (کلیدهایی مثل Geram18، Mazane، Dollar…) با هدر X-API-KEY.
• WS /legacy-ws — هَندشیک {type:"auth", username:"client", password:"<کلید>"}، سپس پاسخ {auth:"ok"} و پیام‌های {status, data, trends}.

در پنل سایت زرنرخ، این همان منبعِ «API جدید» است که با کاربر client و رمزِ برابرِ کلید API وصل می‌شود.

در تب «لاگ دسترسی» هر درخواست (REST یا WS) ثبت می‌شود: زمان، نام کلاینت، IP، مسیر، وضعیت (موفق/ردشده) و مرورگر/کلاینت. می‌توانید بر اساس کلاینت و وضعیت فیلتر کنید. برای عیب‌یابی (مثلاً چرا کلیدی رد می‌شود) بسیار مفید است.

• در تب «کاربران ادمین» می‌توانید برای همکاران، حسابِ ورود به پنل بسازید یا حذف کنید.
• در تب «تنظیمات» رمز عبور خودتان را عوض کنید (حداقل ۸ کاراکتر). رمزها هش‌شده ذخیره می‌شوند.

• کلید را محرمانه نگه دارید. در کدِ سمت‌سرور بگذارید، نه جایی که کاربر ببیند (مگر کلیدِ مخصوصِ نمایشِ عمومی با محدودیت مناسب).
• اگر کلیدی لو رفت، همان را غیرفعال/حذف و کلید جدید بسازید.