مرجع API
ارسال زنده (Server-Sent Events)
GET
https://data.zevix.ir/v1/streamهر تغییر قیمت همان لحظه به برنامه شما فرستاده می‌شود؛ بدون polling و بدون مصرف سهمیه.
اتصال باز می‌ماند و رویداد prices ابتدا یک‌بار با کل تابلو و سپس بعد از هر تغییر قیمت فرستاده می‌شود. بدنه هر رویداد همان شکل پاسخ /v1/prices را دارد.
هر ۲۰ ثانیه یک خط توضیح (: ping) می‌آید تا پروکسی‌ها اتصال را نبندند. اگر کلید باطل یا اشتراک تمام شود رویداد error می‌آید و اتصال بسته می‌شود؛ قطع شبکه را با اتصال دوباره (EventSource خودش انجام می‌دهد) جبران کنید.
حداکثر ۵ اتصال هم‌زمان برای هر کلید. چون EventSource مرورگر هدر نمی‌فرستد، کلید را در api_key بگذارید (و آن کلید را به دامنه سایت خود محدود کنید).
نیازمند پلن
ارسال زنده (پلن حرفه‌ای و سازمانی)
پارامترها
| پارامتر | محل | نوع | توضیح |
|---|---|---|---|
X-API-Key / api_keyالزامی | header | string | کلید، در هدر یا پارامتر api_key |
symbolsاختیاری | query | string | نمادها با کاما؛ خالی یعنی همه — مثال: gold_18,usd |
فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
event: prices | Board | بدنه همان data پاسخ /v1/prices |
event: error | {code, message} | پیش از بسته شدن اتصال به‌خاطر کلید یا اشتراک |
پاسخ‌های خطا
| HTTP | کد | چه وقت | |
|---|---|---|---|
| 401 | api_key_required | هیچ‌کدام از X-API-Key، Authorization: Bearer یا api_key در درخواست نیست. | راه‌حل ← |
| 401 | invalid_api_key | کلید اشتباه تایپ شده، باطل شده یا وجود ندارد. | راه‌حل ← |
| 402 | subscription_expired | پلن فعالی برای حساب نیست (تمام شده یا هنوز نخریده‌اید). | راه‌حل ← |
| 403 | plan_feature_missing | ارسال زنده یا ویجت در پلن شما نیست. | راه‌حل ← |
| 429 | too_many_streams | بیش از ۵ اتصال هم‌زمان /v1/stream با یک کلید. | راه‌حل ← |
| 429 | rate_limited | بیش از سقف پلن در یک دقیقه درخواست داده‌اید. | راه‌حل ← |
| 503 | service_disabled | سرویس‌دهی API برای نگهداری موقتاً خاموش است. | راه‌حل ← |
همه کدها و راه‌حل‌ها: کدهای وضعیت و خطا.
درخواست
// مرورگر یا Node.js 22+
const es = new EventSource("https://data.zevix.ir/v1/stream?symbols=gold_18,usd&api_key=YOUR_API_KEY");
es.addEventListener("prices", (e) => {
const { quotes } = JSON.parse(e.data);
for (const q of quotes) console.log(q.symbol, q.price_toman);
});
es.addEventListener("error", (e) => {
if (e.data) console.error(JSON.parse(e.data)); // کلید باطل یا اشتراک تمام شده
});جریان رویداد
event: prices
data: {"at":"2026-10-02T06:11:40Z","delay_seconds":0,"quotes":[{"symbol":"gold_18","price":"256944000",...}]}
: ping
event: prices
data: {"at":"2026-10-02T06:12:10Z","delay_seconds":0,"quotes":[...]}
event: error
data: {"code":"subscription_expired","message":"اشتراک API به پایان رسیده است"}