trades

HL-compatible real-time trade stream, with optional firehose add-on.

HL-compatible per-coin trade stream. Each message contains a batch of WsTrade objects synthesized from block fills — one per matched (buyer, seller) pair.

Per-coin trades is included in every tier (5/25/100 coins for starter/growth/scale). Streaming all coins with no coins filter is an add-on and requires the ws:allTrades permission.

Subscribe

{
    "type": "subscribe",
    "subscription": {
        "type": "trades",
        "coin": "BTC",                  // optional, single-coin (HL-native shape)
        "coins": ["xyz:SP500", "BTC"]   // optional, multi-coin; omit both for the all-coins firehose
    }
}

Parameter	Type	Description
coin	string	Single-coin filter (HL's native wire shape, accepted for compatibility). Full coin string including any prefix, e.g. "BTC", "xyz:SP500", "#90", "@107" / "PURR/USDC" (spot).
coins	string[]	Multi-coin filter (case-sensitive, up to the tier's max_coins: 5/25/100). Same coin format as coin.

coin and coins may be combined — their union is the effective coin set. Omitting both makes this the all-coins firehose, which requires the ws:allTrades add-on permission.

This is wire-compatible with Hyperliquid: HL clients sending the single coin: "BTC" field work as-is. The coins array is a Hyna extension for subscribing to several coins in one subscription.

One trades subscription per connection. All trades messages share a single trades channel with no per-subscription identity, so the client cannot tell two trades streams apart. A connection may hold at most one trades subscription (per-coin or firehose). To watch several coins, list them all in one subscription's coins array rather than opening multiple subscriptions. A second, distinct trades subscribe on the same connection is rejected with an error; unsubscribe first to switch between a per-coin filter and the firehose. Re-sending the identical subscription is a no-op. Separate connections each get their own trades subscription. The coin cap (5/25/100) is counted cumulatively across the API key.

Unsubscribe

{
    "type": "unsubscribe",
    "subscription": {
        "type": "trades",
        "coins": ["BTC"]
    }
}

Trade data format

The response matches HL's WsTrade shape exactly. Trades are batched per block, ordered by the underlying fill order — ascending (time, tx_index), so the earliest fill in the block appears first.

{
  "type": "trades",
  "seq": 1,
  "cursor": "500:1704067200000:0",
  "trades": [
    {
      "coin": "BTC",
      "side": "B",
      "px": "62541.0",
      "sz": "0.0006",
      "hash": "0xeca4564b44c8a8e5ee1e043e5cac07020fa10030dfcbc7b7906d019e03cc82d0",
      "time": 1782203279565,
      "tid": 414334974001319,
      "users": [
        "0xf83fc34248744a304872e1ed40b9b10f54a64f6f",
        "0x2ca4927174ba283d8a57f60ef3589844035a2930"
      ]
    }
  ]
}

Field semantics:

Field	Description
coin	Coin identifier (matches coins filter format).
side	The taker's side. "B" = taker bought, "A" = taker sold.
px	Trade price.
sz	Trade size.
hash	Fill hash.
time	Trade timestamp (ms).
tid	Trade id. Unique within (coin, time); for a globally unique id use (block_time, coin, tid).
users	[buyer, seller] — matches Hyperliquid. The taker is users[0] when side="B" and users[1] when side="A" (use side to identify the taker).

Common errors

Subscription allTrades requires permission: ws:allTrades

(Only the no-filter firehose form requires the add-on; per-coin trades is included in every tier.)

Examples

Javascript

const WebSocket = require('ws');

const ws = new WebSocket(`wss://api.hydromancer.xyz/ws?token=${process.env.HYDROMANCER_API_KEY}`);

ws.on('message', (data) => {
    const msg = JSON.parse(data);

    if (msg.type === 'connected') {
        ws.send(JSON.stringify({
            type: 'subscribe',
            subscription: { type: 'trades', coins: ['BTC', 'ETH'] }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'trades') {
        for (const t of msg.trades) {
            const [buyer, seller] = t.users;
            console.log(`${t.coin} ${t.side} ${t.sz}@${t.px}  buyer=${buyer} seller=${seller}`);
        }
    }
});

Python