مقدمه
سوکت های والکس امکان دریافت داده‌های لحظه‌ای بازار و رویدادهای خصوصی حساب کاربری را فراهم می‌کنند. بر خلاف REST API که برای هر داده‌ی جدید نیاز به ارسال درخواست دارد، سوکت یک اتصال پایدار می‌سازد و داده را به محض تغییر برای شما ارسال می‌کند.
زیرساخت وب‌سوکت والکس بر پایه‌ی Centrifugo پیاده‌سازی شده است. به این معنی که نحوه‌ی ارتباط، فرمت پیام‌ها و نحوه‌ی عضویت در کانال‌ها از کتابخانه‌ی Centrifugo پیروی می‌کند.
دو ورژن برای استفاده از وب‌سوکت والکس
ورژن ۱ (منسوخ شده)، یعنی ارسال ["subscribe", { "channel": "..." }] به آدرس wss://api.wallex.ir/ws، همچنان پشتیبانی می‌شود و کار می‌کند.
ورژن ۲ (سنتریفیگو) که در این مستندات توضیح داده شده است، روی آدرس wss://api.wallex.ir/connection/websocket در دسترس می‌باشد. جهت پیاده‌سازی‌های جدید استفاده از این ورژن پیشنهاد می‌شود.
در صورتی که قصد دارید یک پیاده‌سازی موجود را منتقل کنید، راهنمای مهاجرت معادل هر بخش را نشان می‌دهد.
آدرس اتصال
wss://api.wallex.ir/connection/websocket
توجه داشته باشید که مسیر باید دقیقاً /connection/websocket باشد. اضافه کردن / در انتهای آدرس باعث خطای 404 می‌شود.
سه روش استفاده
| روش | مناسب برای | مستندات |
|---|---|---|
| ورژن ۱ (منسوخ شده) | پیاده‌سازی‌هایی که از قبل روی wss://api.wallex.ir/ws کار می‌کنند. | بخش «ورژن ۱ (منسوخ شده)» در صفحه‌ی هر کانال |
| ورژن ۲ (سنتریفیگو) با SDK رسمی | اکثر پیاده‌سازی‌های جدید. مدیریت اتصال مجدد و ping/pong خودکار انجام می‌شود. | اتصال و عضویت |
| ورژن ۲ (سنتریفیگو) بدون SDK | زبان‌ها یا محیط‌هایی که SDK ندارند. تمام مراحل باید دستی پیاده‌سازی شود. | اتصال بدون SDK |
SDK های رسمی
| زبان | پکیج |
|---|---|
| JavaScript / TypeScript | centrifuge-js |
| Python | centrifuge-python |
| Go | centrifuge-go |
| Java / Android | centrifuge-java |
| Swift / iOS | centrifuge-swift |
| Dart / Flutter | centrifuge-dart |
برای .NET/C# نیز کتابخانه‌های غیررسمی موجود می‌باشد.
لیست کانال‌ها
نام هر کانال از دو بخش تشکیل شده است: یک namespace و سپس : و نام کانال. توجه داشته باشید که کانالی که : نداشته باشد پذیرفته نمی‌شود.
| کانال | نیاز به لاگین | نحوه‌ی عضویت | مستندات |
|---|---|---|---|
public:<SYMBOL>@trade | خیر | با دستور subscribe | معاملات انجام‌شده |
public:all@price | خیر | با دستور subscribe | قیمت لحظه‌ای |
public:all@fairPrice | خیر | با دستور subscribe | قیمت منصفانه |
orderbook:<SYMBOL>@buyDepth | خیر | با دستور subscribe | عمق بازار خرید |
orderbook:<SYMBOL>@sellDepth | خیر | با دستور subscribe | عمق بازار فروش |
candle:<SYMBOL>@<INTERVAL> | خیر | با دستور subscribe | کندل چارت |
private:user#<userId> | بله | خودکار، توسط سرور | رویدادهای خصوصی |
به جای <SYMBOL> نام مارکت را قرار دهید، مانند BTCTMN یا USDTTMN. نام مارکت فقط می‌تواند شامل حروف انگلیسی، اعداد، _ و - باشد.
به جای <INTERVAL> بازه‌ی زمانی کندل را قرار دهید: 1m (یک‌دقیقه‌ای)، 1h (یک‌ساعته) یا 1d (روزانه). برای مثال candle:USDTTMN@1m.
تاریخچه‌ی پیام‌ها
در ورژن ۲ (سنتریفیگو) فقط کانال‌های کندل (candle:) تاریخچه دارند. هر کانال کندل حداکثر ۱۰ پیام آخر را تا دو دقیقه نگه می‌دارد. پیام‌های این کانال‌ها شماره‌ی ترتیبی (offset) دارند و اعضای کانال می‌توانند این پیام‌ها را با متد history دریافت کنند. جزئیات در کندل چارت آمده است.
بقیه‌ی کانال‌ها فقط پیام‌های جدید را پخش می‌کنند و هیچ پیامی را ذخیره نمی‌کنند. یعنی:
- با عضو شدن هیچ پیامی دریافت نمی‌کنید و اولین پیام زمانی می‌رسد که داده‌ی آن کانال تغییر کند.
- پاسخ دستور
subscribeخالی می‌باشد:{ "id": 2, "subscribe": {} }. نه اسنپ‌شات اولیه دارد و نه فیلدهایrecoverable،epoch،offset،positionedیاrecovered. - پیام‌های دریافتی هم شماره‌ی ترتیبی (
offset) ندارند. - در صورتی که اتصال قطع شود، پیام‌های آن فاصله برای همیشه از دست می‌روند و سرور آن‌ها را دوباره ارسال نمی‌کند.
در ورژن ۱ (منسوخ شده) هم عضو شدن در یک کانال وضعیت فعلی را برای شما ارسال نمی‌کند و باید منتظر اولین تغییر بمانید.
جزئیات ورژن ۱ (منسوخ شده)
ورژن ۱ (wss://api.wallex.ir/ws) منسوخ شده است. این ورژن هنوز کار می‌کند، اما کانال‌های جدید مانند قیمت منصفانه و کندل چارت فقط روی ورژن ۲ (سنتریفیگو) در دسترس هستند.
برای پیاده‌سازی جدید از ورژن ۲ استفاده کنید. برای انتقال کد فعلی، راهنمای مهاجرت را ببینید.
محدودیت‌ها
- اتصال پس از ۳۰ دقیقه بسته می‌شود. پس از آن باید دوباره متصل شوید و دوباره در کانال‌ها عضو شوید.
- در هر اتصال حداکثر ۵۰ بار می‌توانید دستور
subscribeبفرستید. ارسالunsubscribeاین شمارش را کم نمی‌کند. درخواست‌های بیشتر بدون هیچ خطایی نادیده گرفته می‌شوند. - سرور هر ۲۰ ثانیه یک فریم ping استاندارد وب‌سوکت می‌فرستد. اگر پاسخ pong تا ۳۰ ثانیه نرسد، اتصال بسته می‌شود. مرورگرها و بیشتر کتابخانه‌های وب‌سوکت pong را به‌صورت خودکار می‌فرستند.
- ارسال pong فقط اتصال را زنده نگه می‌دارد و مدت آن را بیشتر از ۳۰ دقیقه نمی‌کند.
- فقط پیام متنی (text frame) پذیرفته می‌شود. ارسال پیام باینری اتصال را با کد
1003می‌بندد. - اگر اتصال شما کند باشد و بیش از ۱۰۰ پیام منتظر ارسال بماند، پیام‌های جدید بدون اطلاع حذف می‌شوند.
پیام‌هایی که داده‌ی کانال نیستند
داده‌ی کانال‌ها همیشه به‌صورت آرایه‌ی [نام کانال, بدنه] می‌رسد. سرور دو پیام دیگر هم می‌فرستد که آبجکت هستند، نه آرایه. قبل از خواندن هر پیام به‌عنوان آرایه، این دو را جدا کنید.
اولین پیام پس از اتصال، اطلاعات اتصال است.
{
"sid": "2872283a-ad89-4c4c-9ff1-5874f3d454ad",
"upgrades": [],
"pingInterval": 20000,
"pingTimeout": 30000,
"maxPayload": 1048576
}
| فیلد | نوع | توضیح |
|---|---|---|
sid | String | شناسه‌ی این اتصال |
upgrades | Array | همیشه خالی |
pingInterval | Number | فاصله‌ی ارسال ping توسط سرور، بر حسب میلی‌ثانیه |
pingTimeout | Number | مدت انتظار سرور برای pong، بر حسب میلی‌ثانیه |
maxPayload | Number | حداکثر اندازه‌ی پیامی که می‌توانید ارسال کنید، بر حسب بایت |
اگر آرایه‌ای بفرستید که دستور معتبری نباشد، مانند ["subscribe", {}]، این پیام را دریافت می‌کنید. پیامی که JSON معتبر نباشد بدون هیچ پاسخی نادیده گرفته می‌شود.
{ "error": "invalid subscribe request" }
لغو عضویت
برای خارج شدن از یک کانال، دستور زیر را ارسال کنید. این دستور پاسخی ندارد.
["unsubscribe", { "channel": "BTCTMN@trade" }]
محدودیت‌های ورژن ۲ (سنتریفیگو)
- در هر اتصال حداکثر می‌توانید در ۶۴ کانال عضو شوید. بیشتر از آن با خطای
106: limit exceededرد می‌شود. کانال خصوصی هم در این شمارش حساب می‌شود، پس برای کاربر لاگین‌کرده ۶۳ کانال باقی می‌ماند. - سرور هر ۲۵ ثانیه یک ping می‌فرستد و حداکثر ۸ ثانیه منتظر پاسخ می‌ماند. اگر از SDK استفاده می‌کنید این کار خودکار انجام می‌شود.