[0xFantomMenace]

Summary

Live subscriptions now work for four Lighter channels: lighter_orderbook, lighter_trades, lighter_open_interest and lighter_funding. lighter_candles and lighter_l3_orderbook stay replay-only, and replay of all six Lighter channels is unchanged.

Client

• subscribe() and subscribe_async() take an interval_ms keyword for lighter_orderbook. Books default to one per second; 100 to 5000 ms is accepted. The SDK raises ValueError with the server's wording if it is passed on another channel or is out of range, and with its own message if it is not an integer (the server ignores such a subscribe without replying). It is re-sent on reconnect, and a later subscribe without it goes back to the default, which matches how the server replaces a subscription.
• Live Lighter subscriptions are tracked by the uppercase symbol, as the server treats them, so subscribing as btc and unsubscribing as BTC removes the subscription and it is not restored on reconnect.
• New helpers: subscribe_lighter_orderbook(coin, interval_ms=None), subscribe_lighter_trades, subscribe_lighter_open_interest, subscribe_lighter_funding and the matching unsubscribe_* methods.
• New handlers: on_lighter_orderbook, on_lighter_trades and on_lighter_market_context. When the first two are set they take precedence over on_orderbook and on_trades, so Lighter BTC is not mixed up with Hyperliquid BTC. When they are not set, Lighter books and trades still reach the generic handlers.

Types

• LighterLiveTrade models one live trade leg: two legs per trade share tid, users holds the Lighter account index, and the fee fields and dir are always null.
• LighterMarketContext and LighterMarketContextUpdate model the message that both lighter_open_interest and lighter_funding carry. Fields use the SDK's snake_case names, and the wire camelCase keys are accepted as aliases.
• Live books decode to the existing OrderBook.
• New Trade.account_index field. Live Lighter legs set it, and so do Lighter REST trades, which already return account_index.
• symbol added to WsSubscribed, WsUnsubscribed and WsData.

Docs and release

• The README WebSocket section has a new "Live Lighter.xyz Data" section covering payloads, the interval, lag notices and the two-legs-per-trade counting rule.
• The Lighter channel table and the OI and funding replay note are corrected.
• CHANGELOG entry and version bump to 1.11.0.

Checks

• pytest (Python 3.12): 85 passed. This includes new tests for subscribe serialization with and without interval_ms, boundary and rejection cases, case-insensitive subscription tracking, the replay-only rules, re-sending on reconnect, handler precedence and fallback, and parsing of real production frames for all three payload types.
• tests/test_websocket_capabilities.py on Python 3.9: 60 passed.
• ruff check oxarchive tests and mypy oxarchive: no new findings compared with master. The existing findings are unchanged.
• python -m build: sdist and wheel build. I reproduced the package-contents workflow on a clean clone, with stray files planted as the workflow does. Every packaged file is tracked source or build metadata.
• Ran the branch against wss://api.0xarchive.io/ws:
  • Subscribes were acked with uppercase symbols.
  • Books had 20 levels per side with n=1. BTC arrived about every 250 ms with interval_ms=250 and ETH about once a second by default.
  • Every trade came as two legs, with exactly one taker leg per tid.
  • Market context arrived on both channels.
  • The server's interval_ms error messages match the client-side ones for a wrong channel and an out-of-range value.
  • A btc subscribe is acked as BTC, and a BTC unsubscribe stops it.