Surface parity for 1.12.0: webhooks, CVD, HIP-3 oracle, HIP-4 questions, wallet classification, core breadth, symbols

[0xFantomMenace]

Brings the SDK to parity with the customer-facing API for the 1.12.0 release. Everything is recorded in the existing 1.12.0 CHANGELOG section; the version is unchanged.

Added

• Webhooks: client.webhooks covers all 21 operations under /v1/webhooks, sync and async. That is the event catalog and plan limits; endpoints (list, create, delete, enable, rotate the secret, send a test); the delivery log and redelivery; subscriptions (list, create, update, delete, resume one, resume all); the dry-run and estimate previews; and watched addresses. The code comes from the earlier webhooks branch (Add the webhooks resource and a signature verifier #9, closed when history was rewritten), updated to the current API: limits() and the two resume routes are new, subscriptions report their pause state, and a resume returns the window that was missed.
• Signature verification in oxarchive/webhook_signature.py (WebhookVerifier, verify_webhook() and related helpers):
  • It checks the raw request bytes, because the signature covers the exact bytes sent.
  • It accepts every v1= signature in the header, so a delivery signed during a secret rotation verifies under either secret.
  • It rejects a delivery whose timestamp is more than 5 minutes from now by default.
  • It compares signatures in constant time.
• Cumulative volume delta for Hyperliquid core and HIP-3: cvd.history() returns one page with next_cursor; pass it back unchanged. cvd.iterate() follows the cursor for you.
• HIP-3 oracle: external_price() and discovery_bounds().
• HIP-4 questions: questions.list() and questions.get(), plus flat helpers.
• Wallet classification for Hyperliquid core and HIP-3: wallets.classify(), with every filter, sort and offset-based paging.
• Symbol universe: client.symbols.list().
• Hyperliquid core breadth: client.hyperliquid.breadth, the same resource as HIP-3 breadth.
• Full-depth L2 WebSocket channels orderbook_full and hip3_orderbook_full, with subscribe helpers. They also go into WsChannel; before, their messages failed to parse. Both channels are live-only, so replay() and multi_replay() reject them before sending, as they do for the live-only L4 channels.
• Order-flow paging docs, folded in from HELD until the API returns next_cursor on order flow: document order-flow paging #14: the README example and the flow() docstring now page with next_cursor. flow() and aflow() already send cursor on Hyperliquid, HIP-3 and HIP-4, and new tests cover that.

Removed

Methods that called routes the API does not serve, so every call returned 404 (each route checked on the live API):

• hyperliquid.hip4.l2_orderbook: get, history and diffs.
• hyperliquid.hip4.orders.trigger_levels and trigger_levels_history.
• spot.orders.flow, tpsl, trigger_levels and trigger_levels_history.
• hyperliquid.hip3.liquidations.by_user.

Their async versions go too. The shared resources are split so each venue exposes only what it serves: Hip4OrdersResource, SpotOrdersResource and Hip3LiquidationsResource. A scan of every SDK method against the API contract finds no other unserved route.

Changed

Parameters the API never applied are removed; each was confirmed live to have no effect. Passing one raises TypeError before sending, so the call fails instead of returning unfiltered data as if the filter had worked:

• side on trades.list().
• user, status and order_type on spot.orders.history(). Core, HIP-3 and HIP-4 order history keep them.
• depth on the history() methods of l2_orderbook, l4_orderbook and the Lighter l3_orderbook. It still applies to get().

lighter.l3_orderbook.get() now takes account, and history() takes granularity and account.

Fixed

These existing methods broke on live responses:

• Trades pagination. trades.list() and alist() converted the cursor as if it were a timestamp. A trades cursor is an opaque string ("1790640000578_218303497631402"), so asking for the second page raised ValueError. The cursor is now sent back exactly as returned.
• HIP-4 freshness. CoinFreshness.funding is now optional. HIP-4 has no funding, so hip4.get_freshness() failed validation on every response.
• Symbol coverage. data_quality.symbol_coverage() upper-cased the symbol, turning HIP-3 km:US500 into a symbol with no data. It also left the HIP-4 # unencoded, which cut the path short. The symbol is now sent as given, URL-encoded.
• Spot freshness. SpotTableFreshness expected a tables field the API never sends, so it was always empty. It now has the dataset fields the API returns, and tables lists them.

Notes

• The WebSocket channel docs list historical replay for orderbook_full and hip3_orderbook_full, but the API refuses it. The SDK treats both channels as live-only and points stored full-depth history at the REST l2_orderbook routes.
• Webhook write operations are tested only against a mocked transport.
• The new read methods were checked against live responses: CVD, oracle, questions, classification, symbols, core breadth and the webhook list routes.

Checks

• pytest: 354 passed, 181 of them new.
• mypy --strict still fails on master (325 errors). This branch adds none (304 total), and the new modules type-check clean.
• ruff: no new findings.
• python -m build: passes. The package-contents check passes with planted stray files, and only oxarchive/ ships.