Luồng WebSocket
Hết thời gian kết nối
- Máy chủ đóng kết nối WebSocket sau 60 giây không hoạt động (Kết nối duy trì)
- Không hoạt động được định nghĩa là không có yêu cầu nào được gửi bởi máy khách
Kết nối giữ kết nối
Để giữ kết nối WebSocket hoạt động, bạn cần
- Gửi yêu cầu định kỳ cứ sau 50 giây
- Xử lý đúng cách các ngắt kết nối tiềm ẩn trong logic của ứng dụng của bạn
Ủy quyền
Giới thiệu
Trước khi ký bất kỳ yêu cầu WebSocket nào, bạn phải tạo khóa API trong tài khoản cá nhân Cryptomus của mình
Có hướng dẫn chi tiết để tạo khóa API đây
Nhận mã thông báo một lần để kết nối
Trước khi kết nối với máy chủ WebSocket, bạn cần phải có mã thông báo xác thực một lần
Bạn có thể nhận được mã thông báo bằng cách gửi yêu cầu tương ứng
Mã thông báo có hiệu lực trong 5 phút hoặc cho đến khi kết nối thành công đầu tiên
Kết nối với Máy chủ WebSocket
Để kết nối với máy chủ WebSocket
1. Nhận được một lần mã thông báo xác thực
2. Chỉ định mã thông báo trong tham số truy vấn mã thông báo khi thiết lập kết nối
Ví dụ về URL kết nối: wss://api-ws.cryptomus.com/ws?token=b0b1cacd26993392ecf072155bd1686c96e380ad12cefa564aa6665c85c77334
Mã thông báo chỉ có thể được sử dụng một lần. Với mỗi kết nối mới, bạn cần yêu cầu mã thông báo mới.
Sau khi xác minh mã thông báo thành công, kết nối sẽ được thiết lập và bạn có thể đăng ký các kênh có sẵn
Nhận mã thông báo xác thực một lần cho kết nối WebSocket
Cho phép tạo mã thông báo xác thực một lần để kết nối với máy chủ WebSocket. Mã thông báo có hiệu lực cho đến khi kết nối thành công đầu tiên hoặc cho đến khi hết hạn (5 phút).
GET /v2/user-api/exchange/account/web-socket/token Sao chép
Tiêu đề ủy quyền
Có sẵn thông tin đầy đủ về các tiêu đề ủy quyền bắt buộc đây
Phản ứng
{ "token": "168b34a3a12370740ff1654f0d0c4726ff1bba8c4675edc0d7553f15e5a2a094" }Mã có thể
200: Đơn hàng đã được tạo thành công
404: Không tìm thấy người dùng hoặc tài nguyên
500: Lỗi máy chủ nội bộ
Biểu tượng của thang đo độ sâu
Lời yêu cầu
GET https://exchange-ws.cryptomus.com/api/v2/symbol-scales?symbol={symbol} Sao chép
Phản ứng
1{
2 "status": "success",
3 "message": "success",
4 "data": [
5 {
6 "scale": "0.01",
7 "index": 0 // index
8 },
9 ...
10 ]
11}Danh sách thị trường
Lời yêu cầu
GET https://api-app.cryptomus.com/v1/exchange/market Sao chép
Phản ứng
1{
2 "result": [
3 {
4 "id": "01HSBPVS17CT2GN2FV34K3AMP9",
5 "symbol": "BTC_USDT",
6 "baseCurrency": "BTC",
7 "quoteCurrency": "USDT",
8 "baseMinSize": "0.0000100000000000",
9 "quoteMinSize": "0.1000000000000000",
10 "baseMaxSize": "10000000000.0000000000000000",
11 "quoteMaxSize": "99999999.0000000000000000",
12 "basePrec": "8",
13 "quotePrec": "6",
14 "baseCurrencyFullName": "Bitcoin",
15 "quoteCurrencyFullName": "Tether USD"
16 },
17 ...
18 ]
19}Ví dụ triển khai
Node.js
1const WebSocket = require('ws');
2
3class CryptomusWebSocket {
4 constructor(token) {
5 this.token = token;
6 this.socket = new WebSocket('wss://api-ws.cryptomus.com/ws?token=${this.token}');
7 this.setupConnection();
8 }
9
10 setupConnection() {
11 this.socket.on('open', () => {
12 console.log('Connected to Cryptomus WebSocket');
13 this.startPing();
14 });
15
16 this.socket.on('message', (data) => {
17 console.log('Received:', data.toString());
18 });
19 }
20
21 ping() {
22 if (this.socket.readyState === WebSocket.OPEN) {
23 this.socket.send(JSON.stringify({
24 id: 0,
25 method: "ping",
26 params: []
27 }));
28 }
29 }
30
31 startPing() {
32 setInterval(() => {
33 this.ping();
34 }, 50 * 1000); // Every 50 seconds
35 }
36}
37
38// Usage
39const token = "your_auth_token_here";
40const client = new CryptomusWebSocket(token);
41 Python
1import asyncio
2import websockets
3import json
4
5class CryptomusWebSocket:
6 def __init__(self, token):
7 self.token = token
8 self.socket = None
9
10 async def connect(self):
11 self.socket = await websockets.connect(f"wss://api-ws.cryptomus.com/ws?token={self.token}")
12 print('Connected to Cryptomus WebSocket')
13
14 async def ping(self):
15 await self.socket.send(json.dumps({
16 "id": 0,
17 "method": "ping",
18 "params": []
19 }))
20
21 async def start_ping(self):
22 while True:
23 await asyncio.sleep(50) # Every 50 seconds
24 await self.ping()
25
26 async def listen(self):
27 async for message in self.socket:
28 print(f"Received: {message}")
29
30 async def run(self):
31 await self.connect()
32
33 # Start ping task
34 ping_task = asyncio.create_task(self.start_ping())
35
36 # Listen for messages
37 await self.listen()
38
39# Usage
40token = "your_auth_token_here"
41client = CryptomusWebSocket(token)
42asyncio.run(client.run())
43 Tất cả các điểm cuối trả về thời gian theo định dạng dấu thời gian Unix
Cấu trúc tin nhắn yêu cầu
| Tên | Kiểu tham số | Sự định nghĩa |
|---|---|---|
| id | Integer | Nên là duy nhất để xử lý phản hồi cho yêu cầu của bạn |
| method | String | Tên yêu cầu |
| params | Array | Truyền tham số cho phương thức ở đây |
Kiểu tham số
IntegerSự định nghĩa
Nên là duy nhất để xử lý phản hồi cho yêu cầu của bạnKiểu tham số
StringSự định nghĩa
Tên yêu cầuKiểu tham số
ArraySự định nghĩa
Truyền tham số cho phương thức ở đây
Kết nối WebSocket sẽ bị chấm dứt nếu JSON không hợp lệ được gửi
Các loại tin nhắn và yêu cầu
- Yêu cầu (`ping`, `candles_request`, v.v.)
- Đăng ký (`candles_subscribe`, `lastprice_subscribe`, v.v.). Đăng ký lại với cùng một kiểu dữ liệu sẽ bị hủy.
Tin nhắn phản hồi
| Tên | Kiểu tham số | Sự định nghĩa |
|---|---|---|
| id | Integer | Yêu cầu mã định danh |
| data | Null | nếu yêu cầu không thành công. Nếu thành công, cấu trúc phản hồi cho từng phương thức được hiển thị bên dưới. |
| error | Null | nếu thành công. Nếu có lỗi |
| message | String | |
| code | Integer | Mã lỗi |
Kiểu tham số
IntegerSự định nghĩa
Yêu cầu mã định danhKiểu tham số
NullSự định nghĩa
nếu yêu cầu không thành công. Nếu thành công, cấu trúc phản hồi cho từng phương thức được hiển thị bên dưới.Kiểu tham số
NullSự định nghĩa
nếu thành công. Nếu có lỗiKiểu tham số
IntegerSự định nghĩa
Mã lỗi
Mã: 1. Thông báo: Định dạng thông báo không hợp lệ
Mã: 2. Thông báo: Lỗi khác
Các loại tin nhắn phản hồi
- Kết quả truy vấn
- Trạng thái đăng ký (thành công/thất bại)
- Cập nhật sự kiện
Bóng bàn
Ping
1{
2 "id": 0,
3 "method": "ping",
4 "params": []
5}
6 Phản ứng pong
1{
2 "id": 0,
3 "method": "pong",
4 "data": null,
5 "error": null
6}
7 Ví dụ đăng ký
Lời yêu cầu
1{
2 "id": 0,
3 "method": "trade_subscribe",
4 "params": [
5 "BTC_USDT"
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "trade_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Cập nhật sự kiện
1{
2 "id": 0,
3 "method": "trade_update",
4 "data": [], // See structure for each method below
5 "error": null
6}
7 Giá cuối cùng
Đăng ký
1{
2 "id": 0,
3 "method": "lastprice_subscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "BTC_USDT",
7 "ETH_USDT",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện lastprice_subscribe
1{
2 "id": 0,
3 "method": "lastprice_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "lastprice_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Sự kiện
1{
2 "id": 0,
3 "method": "lastprice_update",
4 "data": {
5 "symbol": "BTC_USDT",
6 "timestamp": 1750953362,
7 "price": "107152.55"
8 },
9 "error": null
10}
11 Hủy đăng ký
Lời yêu cầu
1{
2 "id": 0,
3 "method": "lastprice_unsubscribe",
4 "params": [
5 "BTC_USDT",
6 "ETH_USDT",
7 ...
8 ]
9}
10 Hủy đăng ký tất cả các sự kiện lastprice_unsubscribe
1{
2 "id": 0,
3 "method": "lastprice_unsubscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}Độ sâu
Đăng ký
Đầu tiên bạn cần phải có chỉ số quy mô của thị trường làm thế nào để có được
1{
2 "id": 0,
3 "method": "depth_subscribe",
4 "params": [
5 "BTC_USDT:0", // market:scale_index
6 "BTC_USDT:1",
7 "ETH_USDT:1",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện depth_subscribe
1{
2 "id": 0,
3 "method": "depth_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "depth_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Sự kiện
1{
2 "id": 0,
3 "method": "depth_update",
4 "data": {
5 "symbol": "BTC_USDT",
6 "timestamp": 1750952911,
7 "full_reload": false, // If false, it is a partial update, if true, it is a fully updated orderbook.
8 "scale_index": 0,
9 "asks": [
10 [
11 "107043.93", // price
12 "0.304313" // value
13 ]
14 ],
15 "bids": [
16 [
17 "106976.11",
18 "0" // for partial update - finished orders will be 0
19 ]
20 ]
21 },
22 "error": null
23}
24 Hủy đăng ký
Lời yêu cầu
1{
2 "id": 0,
3 "method": "depth_unsubscribe",
4 "params": [
5 "BTC_USDT:0", // market:scale_index
6 "ETH_USDT:1",
7 ...
8 ]
9}
10 Hủy đăng ký tất cả các sự kiện depth_unsubscribe
1{
2 "id": 0,
3 "method": "depth_unsubscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8 Ticker
Đăng ký
1{
2 "id": 0,
3 "method": "ticker_subscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "BTC_USDT",
7 "ETH_USDT",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện ticker_subscribe
1{
2 "id": 0,
3 "method": "ticker_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "ticker_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Sự kiện
1{
2 "id": 0,
3 "method": "ticker_update",
4 "data": {
5 "symbol": "BTC_USDT",
6 "timestamp": 1750953144,
7 "price": "107090.35",
8 "open": "107042.21",
9 "high": "108248.15",
10 "low": "106573.19",
11 "volume": "1531.027982",
12 "quote_volume": "164564314.80174687",
13 "price_change": "0.04"
14 },
15 "error": null
16}
17 Hủy đăng ký
Lời yêu cầu
1{
2 "id": 0,
3 "method": "ticker_unsubscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "ETH_USDT",
7 ...
8 ]
9}
10 Hủy đăng ký tất cả các sự kiện ticker_unsubscribe
1{
2 "id": 0,
3 "method": "ticker_unsubscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8 Giao dịch
Đăng ký
1{
2 "id": 0,
3 "method": "trade_subscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "BTC_USDT",
7 "ETH_USDT",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện trade_subscribe
1{
2 "id": 0,
3 "method": "trade_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "trade_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Sự kiện
1{
2 "id": 0,
3 "method": "trade_update",
4 "data": {
5 "symbol": "BTC_USDT",
6 "timestamp": 1750953177,
7 "trades": [
8 {
9 "price": 107100.01,
10 "quantity": 0.000254,
11 "timestamp": 1750953177,
12 "direction": "buy"
13 },
14 ...
15 ]
16 },
17 "error": null
18}
19 Hủy đăng ký
Lời yêu cầu
1{
2 "id": 0,
3 "method": "trade_unsubscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "ETH_USDT",
7 ...
8 ]
9}
10 Hủy đăng ký tất cả các sự kiện trade_unsubscribe
1{
2 "id": 0,
3 "method": "trade_unsubscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8 Đơn hàng
Đăng ký
1{
2 "id": 0,
3 "method": "order_subscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "TRX_USDT",
7 "ETH_USDT",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện order_subscribe
1{
2 "id": 0,
3 "method": "order_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "order_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Sự kiện
Đơn hàng đã được tạo
1{
2 "id": "1",
3 "method": "order_update",
4 "data": {
5 "type": "created",
6 "info": {
7 "id": "01JYET5DQ772MPYHHE417FQF1J",
8 "symbol": "TRX_USDT",
9 "orderType": "limit",
10 "direction": "sell",
11 "price": "0.2200000000000000",
12 "quantity": "50.0000000000000000",
13 "value": "11.0000000000000000",
14 "filledQuantity": "0.0000000000000000",
15 "filledValue": "0.0000000000000000",
16 "clientOid": null,
17 "createTs": 1750696376
18 }
19 },
20 "error": null
21}
22 Đơn hàng đã được cập nhật
1{
2 "id": "3",
3 "method": "order_update",
4 "data": {
5 "type": "updated",
6 "info": {
7 "id": "01JYET5DQ772MPYHHE417FQF1J",
8 "symbol": "TRX_USDT",
9 "orderType": "limit",
10 "direction": "sell",
11 "price": "0.2200000000000000",
12 "quantity": "50.0000000000000000",
13 "value": "11.0000000000000000",
14 "filledQuantity": "20.0000000000000000",
15 "filledValue": "4.4000000000000000",
16 "clientOid": null,
17 "createTs": 1750696376,
18 "updateTs": 1750696487,
19 }
20 },
21 "error": null
22}
23 Đơn hàng đã hoàn tất
1{
2 "id": "3",
3 "method": "order_update",
4 "data": {
5 "type": "finished",
6 "info": {
7 "id": "01JYET5DQ772MPYHHE417FQF1J",
8 "symbol": "TRX_USDT",
9 "orderType": "limit",
10 "direction": "sell",
11 "price": "0.2200000000000000",
12 "quantity": "50.0000000000000000",
13 "value": "11.0000000000000000",
14 "filledQuantity": "50.0000000000000000",
15 "filledValue": "11.0000000000000000",
16 "clientOid": null,
17 "createTs": 1750696376,
18 "finishTs": 1750696417,
19 "state": "completed""internalState": "filled"
20 }
21 },
22 "error": null
23}
24 Hủy đăng ký nhận thông tin cập nhật
Từ các thị trường cụ thể
1{
2 "id": 0,
3 "method": "order_unsubscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "ETH_USDT",
7 ...
8 ]
9}
10 Từ tất cả các thị trường
1{
2 "id": 0,
3 "method": "order_unsubscribe",
4 "params": [
5 "all" // Optional, will also work if an empty array is passed in
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8 Số dư
Đăng ký
Tiền tệ cơ sở từ danh sách thị trường
1{
2 "id": 0,
3 "method": "balance_subscribe",
4 "params": [
5 "BTC", // BaseCurrency from market list
6 "TRX,
7 "ETH",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện balance_subscribe
1{
2 "id": 0,
3 "method": "balance_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "method": "balance_subscribe",
4 "data": {
5 "status": "success"
6 },
7 "error": null
8}
9 Sự kiện
1{
2 "id": "4",
3 "method": "balance_update",
4 "data": {
5 "info": {
6 "walletId": "01J7E836F6K5KCX5DP2W0F6FAG",
7 "currencyCode": "USDT",
8 "amount": "50.0000000000000000",
9 "oldBalance": "40000.0000000000000000",
10 "newBalance": "39950.00000000"
11 }
12 },
13 "error": null
14}
15 Hủy đăng ký sự kiện
Từ các loại tiền tệ cụ thể
Tiền tệ cơ sở từ market-list
1{
2 "id": 0,
3 "method": "balance_unsubscribe",
4 "params": [
5 "BTC", // BaseCurrency from market list
6 "ETH",
7 ...
8 ]
9}
10 Từ tất cả các loại tiền tệ
1{
2 "id": 0,
3 "method": "balance_unsubscribe",
4 "params": [
5 "all" // Optional, will also work if an empty array is passed in
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8 Ưu đãi
Đăng ký
1{
2 "id": 0,
3 "method": "deal_subscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "TRX_USDT,
7 "ETH_USDT",
8 ...
9 ]
10}
11 Đăng ký tất cả các sự kiện deal_subscribe
1{
2 "id": 0,
3 "method": "deal_subscribe",
4 "params": [
5 "all" // This also works for other events
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8 Sự kiện
1{
2 "id": "4",
3 "method": "deal_update",
4 "data": {
5 "info": {
6 "dealId": "01JYH50V5VWPP3QTYGM6CPZ0AR",
7 "symbol": "TRX_USDT",
8 "dealState": "completed",
9 "transactionId": "01JYH50V5YM8M3943KJ9HY2VXM",
10 "filledPrice": "0.2726960000000000",
11 "filledQuantity": "100.0000000000000000",
12 "filledValue": "27.2696000000000000",
13 "fee": "1.0907840000000000",
14 "feeCurrency": "USDT",
15 "tradeRole": "taker",
16 "committedAt": 1750774869
17 }
18 },
19 "error": null
20}
21 Hủy đăng ký nhận thông tin cập nhật
Từ các thị trường cụ thể
1{
2 "id": 0,
3 "method": "deal_unsubscribe",
4 "params": [
5 "BTC_USDT", // Market
6 "TRX_USDT,
7 ...
8 ]
9}
10 Từ tất cả các thị trường
1{
2 "id": 0,
3 "method": "deal_unsubscribe",
4 "params": [
5 "all" // Optional, will also work if an empty array is passed in
6 ]
7}
8 Phản ứng
1{
2 "id": 0,
3 "data": {
4 "status": "success"
5 },
6 "error": null
7}
8