Claude Cursor Skill

hyperliquid-websocket

Subscribe to live Hyperliquid data over WebSocket from the desk computer - mids, order book, trades, candles, best bid/offer, and per-account fills, order updates and events - with raw JSON, Python SDK and TypeScript examples, plus how to run a supervised watch that logs to a fil

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download galleonlabs-hypergrok-trading-desk-skills_hyperliquid-websocket-ab7d9cc.zip · 6 KB

Install

skills CLI npx skills add https://github.com/galleonlabs/hypergrok-trading-desk/tree/main/skills/hyperliquid-websocket
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install galleonlabs-hypergrok-trading-desk@llmmart
Git git clone https://github.com/galleonlabs/hypergrok-trading-desk.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole galleonlabs/hypergrok-trading-desk collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Hyperliquid WebSocket

Read-only, no key. Endpoints: wss://api.hyperliquid.xyz/ws (mainnet), wss://api.hyperliquid-testnet.xyz/ws (testnet). Prefer WebSocket over polling for anything continuous: fills, order updates, book and price watches.

Protocol

Subscribe: {"method": "subscribe", "subscription": {...}}. Unsubscribe with "method": "unsubscribe". The server acknowledges with {"channel": "subscriptionResponse", ...} then streams {"channel": "<type>", "data": ...}. The server closes a connection it has not sent a message to for 60 seconds, so on quiet channels send {"method": "ping"} periodically (the SDKs do it for you) and expect {"channel": "pong"}.

Subscription types the desk uses:

Type Subscription JSON Data
Mids for all markets {"type":"allMids"} (optional "dex") {"mids": {"BTC": "97123.5", ...}}
Order book {"type":"l2Book","coin":"ETH"} (optional nSigFigs, mantissa, fast: true for 5 levels) {"coin","time","levels":[bids,asks]}, up to 20 levels a side, pushed on each block at least 0.5 s after the last push
Trades {"type":"trades","coin":"ETH"} array of {coin, side, px, sz, time, hash, tid, users}
Candles {"type":"candle","coin":"ETH","interval":"1m"} {t,T,s,i,o,c,h,l,v,n} updated in place until the bar closes
Best bid/offer {"type":"bbo","coin":"ETH"} {"coin","time","bbo":[bid, ask]}
Asset context {"type":"activeAssetCtx","coin":"ETH"} funding, OI, mark, oracle, premium, volume for one market
Account fills {"type":"userFills","user":"0x..."} {"user","isSnapshot","fills":[...]} (first message is a snapshot)
Order updates {"type":"orderUpdates","user":"0x..."} array of {order:{coin,side,limitPx,sz,oid,timestamp,origSz,cloid}, status, statusTimestamp}
Account events {"type":"userEvents","user":"0x..."} fills, funding, liquidation, non-user cancels; arrives on channel "user"
Account funding {"type":"userFundings","user":"0x..."} hourly funding payments
Per-market account data {"type":"activeAssetData","user":"0x...","coin":"ETH"} leverage setting, max trade sizes, available to trade, mark (perps only)
Account state stream {"type":"clearinghouseState","user":"0x..."} / {"type":"openOrders","user":"0x..."} {dex, user, clearinghouseState:{...REST shape...}} / {dex, user, orders:[...]} (order items carry the frontend fields: isTrigger, triggerPx, orderType, cloid), pushed
TWAP state {"type":"twapStates","user":"0x...","dex":""} / {"type":"userTwapSliceFills","user":"0x..."} running TWAPs and their slice fills
Frontend snapshot {"type":"webData3","user":"0x..."} positions, orders and context in one stream (heavy)

Limits per IP: up to 10 connections, 30 new connections per minute, 1000 subscriptions, 10 distinct users across user subscriptions, 2000 messages per minute, 100 in-flight posts. One connection per watch process is enough.

You can also send /info requests over the socket: {"method":"post","id":1,"request":{"type":"info","payload":{"type":"allMids"}}} returns {"channel":"post","data":{"id":1,"response":{"type":"info","payload":{"type":"allMids","data":{...}}}}}, so a watch need not mix REST and WS.

Python (official SDK)

import os, json, sys, time, signal
from hyperliquid.info import Info
from hyperliquid.utils import constants

NETWORK = os.environ.get("HYPERLIQUID_NETWORK", "testnet")
BASE = constants.MAINNET_API_URL if NETWORK == "mainnet" else constants.TESTNET_API_URL
ADDR = os.environ.get("HYPERLIQUID_ACCOUNT_ADDRESS")
LOG = open("/workspace/trading-desk/watch/ws.log", "a")

def on_msg(msg):
    line = json.dumps({"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "channel": msg.get("channel"), "data": msg.get("data")})
    LOG.write(line + "\n"); LOG.flush()
    if msg.get("channel") == "userFills" and not msg["data"].get("isSnapshot"):
        for f in msg["data"]["fills"]:
            print(f"FILL {f['coin']} {f['side']} {f['sz']} @ {f['px']} fee {f['fee']} oid {f['oid']} cloid {f.get('cloid')}", flush=True)

info = Info(BASE)                                   # skip_ws=False starts the socket thread
info.subscribe({"type": "allMids"}, on_msg)
info.subscribe({"type": "l2Book", "coin": "ETH"}, on_msg)
if ADDR:
    info.subscribe({"type": "userFills", "user": ADDR}, on_msg)
    info.subscribe({"type": "orderUpdates", "user": ADDR}, on_msg)   # one orderUpdates/userEvents subscription per Info

signal.signal(signal.SIGTERM, lambda *_: (info.disconnect_websocket(), sys.exit(0)))
while True:
    time.sleep(60)

The SDK's manager pings for you but does not reconnect on drop; run it under a supervisor (see below) and treat a silent log as a dead watch. It also only routes these subscription types to your callback: allMids, l2Book, trades, candle, bbo, userEvents, userFills, orderUpdates, userFundings, userNonFundingLedgerUpdates, activeAssetCtx, activeAssetData. Others in the table (clearinghouseState, openOrders, twapStates, userTwapSliceFills, webData3, notification) are acknowledged by the server but silently dropped by the Python SDK; use the raw socket or the TypeScript client for those. The SDK routes one more type, webData2, but do not subscribe to it: the live server rejects that frame on mainnet and testnet with {"channel":"error"} and the watch never starts. webData2 survives only as an /info request; the frontend snapshot stream is webData3, which SDK 0.24.0 cannot route at all.

Run in the background from the desk computer:

mkdir -p /workspace/trading-desk/watch
nohup python3 /workspace/trading-desk/watch/ws_watch.py >> /workspace/trading-desk/watch/ws_watch.out 2>&1 &
echo $! > /workspace/trading-desk/watch/ws_watch.pid

Heartbeat check for a routine: tail -1 /workspace/trading-desk/watch/ws.log should be recent; if the pid is gone or the log exceeds the watch's staleness bound, mark the watch unavailable, restart it and complete the recovery below. A new PID or subscription acknowledgement does not prove that missed account activity has been recovered.

TypeScript (@nktkas/hyperliquid)

import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
const isTestnet = (process.env.HYPERLIQUID_NETWORK ?? "testnet") !== "mainnet";
const transport = new WebSocketTransport({ isTestnet });     // auto-reconnect and re-subscribe by default
const subs = new SubscriptionClient({ transport });
const user = process.env.HYPERLIQUID_ACCOUNT_ADDRESS as `0x${string}`;

await subs.allMids((d) => console.log("mids", d.mids.ETH));
await subs.l2Book({ coin: "ETH" }, (d) => console.log("book", d.levels[0][0], d.levels[1][0]));
await subs.userFills({ user }, (d) => { if (!d.isSnapshot) console.log("fills", d.fills); });
const s = await subs.orderUpdates({ user }, (u) => console.log("orders", u), { onError: (e) => console.error(e) });
// await s.unsubscribe(); transport.close();

The callback examples above are live notifications, not a complete account journal. They suppress snapshot alerts to avoid announcing old fills as new, but snapshots still need reconciliation and de-duplication before they can support risk decisions.

Recover after a gap or restart

Treat account events as prompts to reconcile, not proof of a gap-free history. On a disconnect, stale heartbeat, process restart or uncertain event order, record the last good UTC time, alert unavailable, and pause new-risk sends. Retain pending risk reservations and the daily-stop latch; restarting does not clear either.

  1. Re-establish the account subscriptions and confirm their acknowledgements. Record a new connection generation so cached messages and old snapshots cannot satisfy recovery.
  2. Fetch fresh /info account state, frontendOpenOrders, and order statuses for every outstanding ticket after reconnect. Recover userFillsByTime from an overlap before the last good time through the new reads, with pagination. At desk startup use the last durable reconciliation time; if it is absent or outside the retained history, say that coverage is unavailable.
  3. Merge REST history and streamed fills without double counting, using account/network plus (time, coin, tid) as the fill identity. Include snapshot fills not already processed. Preserve equal-timestamp boundaries when paging; a saturated page with no forward progress is incomplete evidence, not the end of history.
  4. Compare positions, orders, protection and proposal reservations. Separate responses are not atomic: if account activity occurs during the reads or they disagree, refresh the affected state. Keep unknown sends reserved and follow desk-execution-protocol; silence never resolves them.
  5. Record the recovery window, sources, timestamps and any unresolved gaps. Risk permits new risk only after coverage is complete, the account agrees with the reconciled journal, and a fresh capacity check passes. Report the recovery once. If evidence remains incomplete, keep new risk paused and route protection or exits through the normal approval gates using verified live state.

For a public price/book watch, refresh that market's snapshot and reset its condition baseline before reporting an unchanged result. A recovered price feed alone cannot restore account readiness.

Raw (websocat or any client)

websocat wss://api.hyperliquid-testnet.xyz/ws <<'EOF'
{"method":"subscribe","subscription":{"type":"allMids"}}
EOF

Watch pattern

A watch is a condition plus an alert (desk-monitoring). Structure every watch as: subscribe, log everything to a file, evaluate the condition on each message, post the alert once (with value, threshold, source, UTC time), then either exit or keep watching, and never call /exchange.

Pitfalls

  • Treating the first userFills message as new fills; it is a snapshot (isSnapshot: true).
  • Candle messages repeat for the open bar; act on bar close (T reached) unless you want intrabar updates.
  • Spot coins are named @<index> on the wire (except a few like PURR/USDC); resolve via spotMeta.
  • Silent disconnects. Log a heartbeat and supervise.
  • Running many watches on the shared computer; each is a process. Keep it to what the desk needs.
Files (hypergrok-trading-desk)
  • ATTRIBUTION.md 2.2 KB
    Loading…
  • LICENSE 1 KB · in bundle
  • SKILL.md 10.7 KB
    ---
    name: hyperliquid-websocket
    description: Subscribe to live Hyperliquid data over WebSocket from the desk computer - mids, order book, trades, candles, best bid/offer, and per-account fills, order updates and events - with raw JSON, Python SDK and TypeScript examples, plus how to run a supervised watch that logs to a file and alerts. Read-only. Use for monitoring, fill notifications and any watch that polling would make expensive.
    license: MIT
    metadata:
      version: "1.0.2"
      author: Galleon Labs
      category: hyperliquid
      network-default: testnet
    ---
    
    # Hyperliquid WebSocket
    
    Read-only, no key. Endpoints: `wss://api.hyperliquid.xyz/ws` (mainnet), `wss://api.hyperliquid-testnet.xyz/ws` (testnet). Prefer WebSocket over polling for anything continuous: fills, order updates, book and price watches.
    
    ## Protocol
    
    Subscribe: `{"method": "subscribe", "subscription": {...}}`. Unsubscribe with `"method": "unsubscribe"`. The server acknowledges with `{"channel": "subscriptionResponse", ...}` then streams `{"channel": "<type>", "data": ...}`. The server closes a connection it has not sent a message to for 60 seconds, so on quiet channels send `{"method": "ping"}` periodically (the SDKs do it for you) and expect `{"channel": "pong"}`.
    
    Subscription types the desk uses:
    
    | Type | Subscription JSON | Data |
    | --- | --- | --- |
    | Mids for all markets | `{"type":"allMids"}` (optional `"dex"`) | `{"mids": {"BTC": "97123.5", ...}}` |
    | Order book | `{"type":"l2Book","coin":"ETH"}` (optional `nSigFigs`, `mantissa`, `fast: true` for 5 levels) | `{"coin","time","levels":[bids,asks]}`, up to 20 levels a side, pushed on each block at least 0.5 s after the last push |
    | Trades | `{"type":"trades","coin":"ETH"}` | array of `{coin, side, px, sz, time, hash, tid, users}` |
    | Candles | `{"type":"candle","coin":"ETH","interval":"1m"}` | `{t,T,s,i,o,c,h,l,v,n}` updated in place until the bar closes |
    | Best bid/offer | `{"type":"bbo","coin":"ETH"}` | `{"coin","time","bbo":[bid, ask]}` |
    | Asset context | `{"type":"activeAssetCtx","coin":"ETH"}` | funding, OI, mark, oracle, premium, volume for one market |
    | Account fills | `{"type":"userFills","user":"0x..."}` | `{"user","isSnapshot","fills":[...]}` (first message is a snapshot) |
    | Order updates | `{"type":"orderUpdates","user":"0x..."}` | array of `{order:{coin,side,limitPx,sz,oid,timestamp,origSz,cloid}, status, statusTimestamp}` |
    | Account events | `{"type":"userEvents","user":"0x..."}` | fills, funding, liquidation, non-user cancels; arrives on channel `"user"` |
    | Account funding | `{"type":"userFundings","user":"0x..."}` | hourly funding payments |
    | Per-market account data | `{"type":"activeAssetData","user":"0x...","coin":"ETH"}` | leverage setting, max trade sizes, available to trade, mark (perps only) |
    | Account state stream | `{"type":"clearinghouseState","user":"0x..."}` / `{"type":"openOrders","user":"0x..."}` | `{dex, user, clearinghouseState:{...REST shape...}}` / `{dex, user, orders:[...]}` (order items carry the frontend fields: `isTrigger`, `triggerPx`, `orderType`, `cloid`), pushed |
    | TWAP state | `{"type":"twapStates","user":"0x...","dex":""}` / `{"type":"userTwapSliceFills","user":"0x..."}` | running TWAPs and their slice fills |
    | Frontend snapshot | `{"type":"webData3","user":"0x..."}` | positions, orders and context in one stream (heavy) |
    
    Limits per IP: up to 10 connections, 30 new connections per minute, 1000 subscriptions, 10 distinct users across user subscriptions, 2000 messages per minute, 100 in-flight posts. One connection per watch process is enough.
    
    You can also send `/info` requests over the socket: `{"method":"post","id":1,"request":{"type":"info","payload":{"type":"allMids"}}}` returns `{"channel":"post","data":{"id":1,"response":{"type":"info","payload":{"type":"allMids","data":{...}}}}}`, so a watch need not mix REST and WS.
    
    ## Python (official SDK)
    
    ```python
    import os, json, sys, time, signal
    from hyperliquid.info import Info
    from hyperliquid.utils import constants
    
    NETWORK = os.environ.get("HYPERLIQUID_NETWORK", "testnet")
    BASE = constants.MAINNET_API_URL if NETWORK == "mainnet" else constants.TESTNET_API_URL
    ADDR = os.environ.get("HYPERLIQUID_ACCOUNT_ADDRESS")
    LOG = open("/workspace/trading-desk/watch/ws.log", "a")
    
    def on_msg(msg):
        line = json.dumps({"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "channel": msg.get("channel"), "data": msg.get("data")})
        LOG.write(line + "\n"); LOG.flush()
        if msg.get("channel") == "userFills" and not msg["data"].get("isSnapshot"):
            for f in msg["data"]["fills"]:
                print(f"FILL {f['coin']} {f['side']} {f['sz']} @ {f['px']} fee {f['fee']} oid {f['oid']} cloid {f.get('cloid')}", flush=True)
    
    info = Info(BASE)                                   # skip_ws=False starts the socket thread
    info.subscribe({"type": "allMids"}, on_msg)
    info.subscribe({"type": "l2Book", "coin": "ETH"}, on_msg)
    if ADDR:
        info.subscribe({"type": "userFills", "user": ADDR}, on_msg)
        info.subscribe({"type": "orderUpdates", "user": ADDR}, on_msg)   # one orderUpdates/userEvents subscription per Info
    
    signal.signal(signal.SIGTERM, lambda *_: (info.disconnect_websocket(), sys.exit(0)))
    while True:
        time.sleep(60)
    ```
    
    The SDK's manager pings for you but does **not** reconnect on drop; run it under a supervisor (see below) and treat a silent log as a dead watch. It also only routes these subscription types to your callback: `allMids`, `l2Book`, `trades`, `candle`, `bbo`, `userEvents`, `userFills`, `orderUpdates`, `userFundings`, `userNonFundingLedgerUpdates`, `activeAssetCtx`, `activeAssetData`. Others in the table (`clearinghouseState`, `openOrders`, `twapStates`, `userTwapSliceFills`, `webData3`, `notification`) are acknowledged by the server but silently dropped by the Python SDK; use the raw socket or the TypeScript client for those. The SDK routes one more type, `webData2`, but do not subscribe to it: the live server rejects that frame on mainnet and testnet with `{"channel":"error"}` and the watch never starts. `webData2` survives only as an `/info` request; the frontend snapshot stream is `webData3`, which SDK 0.24.0 cannot route at all.
    
    Run in the background from the desk computer:
    
    ```bash
    mkdir -p /workspace/trading-desk/watch
    nohup python3 /workspace/trading-desk/watch/ws_watch.py >> /workspace/trading-desk/watch/ws_watch.out 2>&1 &
    echo $! > /workspace/trading-desk/watch/ws_watch.pid
    ```
    
    Heartbeat check for a routine: `tail -1 /workspace/trading-desk/watch/ws.log` should be recent; if the pid is gone or the log exceeds the watch's staleness bound, mark the watch unavailable, restart it and complete the recovery below. A new PID or subscription acknowledgement does not prove that missed account activity has been recovered.
    
    ## TypeScript (`@nktkas/hyperliquid`)
    
    ```ts
    import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
    const isTestnet = (process.env.HYPERLIQUID_NETWORK ?? "testnet") !== "mainnet";
    const transport = new WebSocketTransport({ isTestnet });     // auto-reconnect and re-subscribe by default
    const subs = new SubscriptionClient({ transport });
    const user = process.env.HYPERLIQUID_ACCOUNT_ADDRESS as `0x${string}`;
    
    await subs.allMids((d) => console.log("mids", d.mids.ETH));
    await subs.l2Book({ coin: "ETH" }, (d) => console.log("book", d.levels[0][0], d.levels[1][0]));
    await subs.userFills({ user }, (d) => { if (!d.isSnapshot) console.log("fills", d.fills); });
    const s = await subs.orderUpdates({ user }, (u) => console.log("orders", u), { onError: (e) => console.error(e) });
    // await s.unsubscribe(); transport.close();
    ```
    
    The callback examples above are live notifications, not a complete account journal. They suppress snapshot alerts to avoid announcing old fills as new, but snapshots still need reconciliation and de-duplication before they can support risk decisions.
    
    ## Recover after a gap or restart
    
    Treat account events as prompts to reconcile, not proof of a gap-free history. On a disconnect, stale heartbeat, process restart or uncertain event order, record the last good UTC time, alert `unavailable`, and pause new-risk sends. Retain pending risk reservations and the daily-stop latch; restarting does not clear either.
    
    1. Re-establish the account subscriptions and confirm their acknowledgements. Record a new connection generation so cached messages and old snapshots cannot satisfy recovery.
    2. Fetch fresh `/info` account state, `frontendOpenOrders`, and order statuses for every outstanding ticket after reconnect. Recover `userFillsByTime` from an overlap before the last good time through the new reads, with pagination. At desk startup use the last durable reconciliation time; if it is absent or outside the retained history, say that coverage is unavailable.
    3. Merge REST history and streamed fills without double counting, using account/network plus `(time, coin, tid)` as the fill identity. Include snapshot fills not already processed. Preserve equal-timestamp boundaries when paging; a saturated page with no forward progress is incomplete evidence, not the end of history.
    4. Compare positions, orders, protection and proposal reservations. Separate responses are not atomic: if account activity occurs during the reads or they disagree, refresh the affected state. Keep unknown sends reserved and follow `desk-execution-protocol`; silence never resolves them.
    5. Record the recovery window, sources, timestamps and any unresolved gaps. Risk permits new risk only after coverage is complete, the account agrees with the reconciled journal, and a fresh capacity check passes. Report the recovery once. If evidence remains incomplete, keep new risk paused and route protection or exits through the normal approval gates using verified live state.
    
    For a public price/book watch, refresh that market's snapshot and reset its condition baseline before reporting an unchanged result. A recovered price feed alone cannot restore account readiness.
    
    ## Raw (websocat or any client)
    
    ```bash
    websocat wss://api.hyperliquid-testnet.xyz/ws <<'EOF'
    {"method":"subscribe","subscription":{"type":"allMids"}}
    EOF
    ```
    
    ## Watch pattern
    
    A watch is a condition plus an alert (`desk-monitoring`). Structure every watch as: subscribe, log everything to a file, evaluate the condition on each message, post the alert once (with value, threshold, source, UTC time), then either exit or keep watching, and never call `/exchange`.
    
    ## Pitfalls
    
    - Treating the first `userFills` message as new fills; it is a snapshot (`isSnapshot: true`).
    - Candle messages repeat for the open bar; act on bar close (`T` reached) unless you want intrabar updates.
    - Spot coins are named `@<index>` on the wire (except a few like `PURR/USDC`); resolve via `spotMeta`.
    - Silent disconnects. Log a heartbeat and supervise.
    - Running many watches on the shared computer; each is a process. Keep it to what the desk needs.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.