WebSocket

WebSocket API for Astros

Endpoint: wss://api.astros.ag/api/market/ws

All WebSocket subscriptions require API key authentication. Sign the timestamp string with HMAC-SHA256 using app_secret (lowercase hex), the same algorithm as REST.

Keepalive (ping / pong)

Clients should implement an application-level ping/pong heartbeat. The server closes idle connections after about 120 seconds with no inbound traffic. Send a ping on a fixed interval (recommended every 15–30 seconds) and reconnect if no pong arrives.

Text ping / pong (recommended)

Send the plain text frame ping (exactly four characters, case-insensitive). The server replies with the plain text frame pong.

Direction	Frame type	Payload
Client → server	Text	ping
Server → client	Text	pong

Example (browser / Node)

const ws = new WebSocket('wss://api.astros.ag/api/market/ws');

ws.onopen = () => {
  // Heartbeat: ping every 20s
  setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send('ping');
    }
  }, 20_000);
};

ws.onmessage = (event) => {
  if (event.data === 'pong') {
    // connection is healthy
    return;
  }
  // handle subscribe ack / channel pushes...
  console.log(JSON.parse(event.data));
};

Example (Python)

import asyncio
import websockets

async def run():
    uri = 'wss://api.astros.ag/api/market/ws'
    async with websockets.connect(uri) as ws:
        async def heartbeat():
            while True:
                await ws.send('ping')
                await asyncio.sleep(20)

        asyncio.create_task(heartbeat())

        async for message in ws:
            if message == 'pong':
                continue
            # handle JSON subscribe / push messages
            print(message)

asyncio.run(run())

Protocol-level WebSocket ping

The server also answers standard WebSocket Ping control frames with a Pong control frame. Prefer the text ping / pong exchange above when your client library makes application messages easier to handle than control frames.

Client recommendations

• Start the heartbeat as soon as the socket opens, before or after subscribe.

• Treat a missed pong (for example no reply within 10 seconds) as a dead connection: close and reconnect with backoff.

• Do not rely on subscribe traffic alone to keep the socket alive during quiet markets.

Subscription envelope

Every subscribe request shares these fields:

Name	Type	Required	Description
method	String	Yes	SUBSCRIBE
event	String	Yes	Channel name, e.g. api_account
apiKey	String	Yes	Your API key
timestamp	Number	Yes	Unix time in milliseconds
signature	String	Yes	HMAC-SHA256 of the timestamp string

Channel-specific fields (such as symbol, pair, period) are documented per event below.

Sign a subscribe request

1. Take the current timestamp, e.g. 1657157345159

2. Sign the string "1657157345159" with HMAC-SHA256

3. Attach apiKey, timestamp, and signature to the subscribe payload

{
  "symbol": "ETH",
  "method": "SUBSCRIBE",
  "apiKey": "xx",
  "event": "api_account",
  "timestamp": 1657157345159,
  "signature": "f74f11beb8e24cf8a1c5bc8af2fba15446c7806cc12ae09e0dee5b2dd8eef76d"
}

---

Account

event: api_account

Extra request fields

Name	Type	Required	Description
symbol	String	Yes	Settlement coin, e.g. USD

Subscribe

{
  "symbol": "USD",
  "method": "SUBSCRIBE",
  "event": "api_account",
  "apiKey": "xx",
  "signature": "cea09113cb6af891dd620315dcf4316a557ddac28377cb341920d8b0b50eb872",
  "timestamp": 1715049419673
}

Ack

{
  "event": "api_account_res",
  "method": "SUBSCRIBE",
  "msg": "subscribe success: api_account",
  "success": true,
  "symbol": "USD"
}

Push

{
  "data": {
    "availableAmount": "707.729782",
    "coinId": 4,
    "frozenAmount": "1682.041309",
    "logId": 0,
    "operateAmount": "0.00",
    "symbol": "USD"
  },
  "event": "api_account",
  "success": true,
  "symbol": "USD"
}

---

Order updates

event: api_entrust

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair, e.g. ETH-USD

Subscribe

{
  "pair": "ETH-USD",
  "method": "SUBSCRIBE",
  "apiKey": "xx",
  "signature": "dcbfb54c06c04b214de4b63d86b761c1cd3d7427c829e36684b7b2fafa7492c3",
  "event": "api_entrust",
  "timestamp": 1715050200673
}

Push

{
  "data": {
    "changeType": "TRADE",
    "clientOrderId": "17163700712771",
    "contractPairId": 1,
    "currentEntrustId": 78315117,
    "dealAmount": "0",
    "dealQuantity": "0.01",
    "direction": "LONG",
    "feeAmt": "0.022602",
    "feeCoin": "USD",
    "isClose": false,
    "isMarket": true,
    "isTaker": true,
    "lever": 4,
    "matchType": 1,
    "nowDealQuantity": "0.01",
    "price": "3768.953535",
    "quantity": "0.01",
    "symbol": "ETH-USD"
  },
  "event": "api_entrust",
  "success": true
}

---

Position updates

event: api_position

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair

Push

{
  "data": {
    "canClosedQuantity": "0.07",
    "changeType": "NEW",
    "contractPairId": 1,
    "currentQuantity": "0.07",
    "direction": "SHORT",
    "marginAmount": "10.907512",
    "marginCallAmount": "0",
    "openingPrice": "3116.431999",
    "operateQuantity": "0",
    "positionId": 1088968,
    "positionType": 3,
    "symbol": "ETH-USD"
  },
  "event": "api_position",
  "success": true
}

---

Kline

event: api_kline

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair
period	String	Yes	e.g. 1MIN

Push

{
  "contractPairId": 1,
  "data": {
    "amount": 0,
    "close": 3084.91,
    "contractPairId": 1,
    "count": 0,
    "hight": 3084.91,
    "low": 3084.91,
    "open": 3084.91,
    "period": "1MIN",
    "quantity": 0,
    "time": 1715050620000
  },
  "event": "api_kline",
  "period": "1MIN",
  "success": true
}

---

Order book

event: api_depth

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair

Push

{
  "data": {
    "asks": [
      { "price": "3123.86", "quantity": "12.641" },
      { "price": "3165.74", "quantity": "7.358" }
    ],
    "bids": [
      { "price": "3047.05", "quantity": "10.592" },
      { "price": "2983.75", "quantity": "7.868" }
    ]
  },
  "event": "api_depth",
  "pair": "ETH-USD",
  "success": true
}

---

Recent trades

event: api_trade

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair
period	String	No	Channel period if required by server

Push

{
  "data": [
    {
      "amount": 2306.9816,
      "contractMatchPairId": 7890741,
      "contractPairId": 1,
      "isLong": false,
      "pair": "ETH-USD",
      "price": 3084.2,
      "quantity": 0.748,
      "time": "03:00:25",
      "timestamp": 1715050825000
    }
  ],
  "event": "api_trade",
  "pair": "ETH-USD",
  "success": true
}

---

Live trade prints

event: api_spot_deals

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair

Push

{
  "contractPairId": 1,
  "data": {
    "amount": 2300.01498,
    "contractMatchPairId": 7891127,
    "contractPairId": 1,
    "isLong": true,
    "pair": "ETH-USD",
    "price": 3083.13,
    "quantity": 0.746,
    "time": "03:09:05",
    "timestamp": 1715051345000
  },
  "event": "api_spot_deals",
  "pair": "ETH-USD",
  "success": true
}

---

User fills

event: api_deal_user

Extra request fields

Name	Type	Required	Description
pair	String	Yes	Trading pair

Push

{
  "data": {
    "contractPairId": 1,
    "currentEntrustId": 78312005,
    "dealAmount": "37.6773",
    "dealPrice": "3767.73",
    "dealQuantity": "0.01",
    "dealTime": "1716369742538",
    "direction": "LONG",
    "feeAmt": "0.022606",
    "feeCoin": "USD",
    "isClose": false,
    "isTaker": true,
    "matchId": 9280079,
    "matchType": 1,
    "symbol": "ETH-USD"
  },
  "event": "api_deal_user",
  "success": true
}