سرور با فاصله‌ای که در تب «API ورودی» تنظیم می‌شود (اکنون هر ۵ ثانیه) قیمت‌ها را از منبع اصلی (mazanehamrah) می‌خواند و در حافظه کش می‌کند. یک منبع دوم به نام «زربها» هم دارد که از فید سایت zarnerkh.ir تغذیه می‌شود (بخش «منبع دوم — زربها» در همین راهنما). کلاینت‌های شما به‌جای تماس مستقیم با منابع، به این سرویس وصل می‌شوند و با یک کلید دسترسی (که در همین پنل می‌سازید) داده می‌گیرند. مزایا:

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

[mazanehamrah] ──poll (تنظیم از پنل)──▶ [کش + محاسبهٔ change] ──┬─▶ REST  /v1/prices , /legacy/prices
   (کلید مخفی)                                                  ├─▶ WS    /ws , /legacy-ws
[زربها] ──فید WS سایت zarnerkh.ir──▶ [کش زربها] ────────────────┴─▶ REST  /v1/zarbaha  (+ تکمیل Ons/Yuan در legacy)

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 وصل می‌شود.

کلیدهایی که در منبع اصلی معادل ندارند (مثل Ons و Yuan) در صورت فعال بودن منبع دوم «زربها» از آن تکمیل می‌شوند (قابل خاموش‌کردن با تیک «تکمیل کلیدهای خالی» در تب «API ورودی»). تاریخچهٔ این کلیدها هم از همان لحظه در /v1/history ثبت می‌شود.

در تب «API ورودی»، زیر کارت منبع اصلی، کارت «منبع دوم — زربها» هست: قیمت‌های زربها (کلیدهای مسطح با High/Low روزانه از ۹ صبح تهران و روند up/down) که حدوداً هر ۳۵ ثانیه تازه می‌شوند و از مسیر GET /v1/zarbaha (با کلید) در دسترس کلاینت‌ها هستند.

دو حالت دریافت:

• از فید سایت (پیش‌فرض): اتصال WS به wss://zarnerkh.ir/ws/zarbaha — سایت zarnerkh.ir خودش با حساب زربها poll می‌کند و این سرویس فقط مشترکِ همان فید است. بدون مصرف سهمیهٔ اضافه.
• مستقیم از API زربها: فقط وقتی حساب جداگانه دارید. زربها به هر حساب فقط یک درخواست موفق در هر ~۳۰ ثانیه می‌دهد؛ اگر دو poller با یک حساب بزنند، خطای «درخواست زودتر از تایمر ارسال شده» می‌گیرند. دکمهٔ «تست» در این حالت هم یک سهمیهٔ ~۳۰ ثانیه‌ای مصرف می‌کند.

تاریخچهٔ معماری (شهریور ۱۴۰۵): سرور پایتون قدیمی (gold-updater روی پورت 8443) بازنشسته شد؛ خواندن از زربها به داخل خود سایت zarnerkh.ir منتقل شد و آدرس قدیمی wss://price.zarnerkh.ir:8443 برای کلاینت‌های قدیمی (zarbord.ir، talayeroya و…) به‌صورت پروکسی nginx به فید جدید سایت زنده نگه داشته شده است. گواهی آن با certbot تمدید خودکار می‌شود. برای کلاینت‌های جدید، همان GET /v1/zarbaha یا فید سایت توصیه می‌شود.

curl -H "X-API-KEY: zk_YOUR_KEY" https://api.zarnerkh.ir/v1/zarbaha
// → { success, source:"zarbaha", mode, updated_at, stale, unit:"toman",
//     data:{ Geram18, Ons, Dollar, …, Geram18_High24h, Geram18_Low24h, Date, Time },
//     trends:{ Geram18:{prev,trend}, … } }   — غیرفعال/بدون داده → 503

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

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

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