[RFC] Hyperliquid HIP-4 outcome markets integration

[graceyangfan]

Description

Context

NautilusTrader has an official Hyperliquid integration (spot/perps), but it does not currently support Hyperliquid predicted markets (HIP-4 outcome markets).

Hyperliquid exposes outcome market metadata via POST /info with { "type": "outcomeMeta" }.

Hyperliquid also documents the outcome asset encoding:

• encoding = 10 * outcome + side
• outcome market coin: #<encoding>
• outcome action asset id: 100_000_000 + encoding

This RFC proposes adding official adapter support for outcome markets:

• instrument discovery + model mapping
• market data subscriptions (quotes/trades/order book where available)
• order entry/cancel for outcome assets
• recurring market refresh / rotation support

Why?

• Outcome markets are a new instrument class not covered by spot/perps.
• The metadata endpoint + asset encoding are documented and appear stable enough to integrate behind an opt-in flag.
• Recurring markets (daily / 15m / etc.) are a good fit for systematic strategies, but require correct rotation handling.

Proposed Scope

Instruments

• Add HyperliquidProductType.OUTCOME as an opt-in product type for Hyperliquid data/execution clients.

• Load outcome instrument definitions from outcomeMeta.

• Map outcomes to BinaryOption instruments with a stable InstrumentId scheme:

  • OUTCOME-{outcome_id}-{YES|NO}-OUTCOME.HYPERLIQUID

• Persist the raw-symbol and action-asset mapping per docs:

  • raw_symbol = #<encoding> where encoding = outcome_id * 10 + side
  • asset_id = 100_000_000 + encoding

• Parse the description strings into structured metadata, and attach it to BinaryOption.info (e.g. class, underlying, period, expiry, targetPrice, priceThresholds, etc.).

Market data

• Enable WS subscriptions for outcomes (BBO/trades/book where supported for #<encoding> coins).

Execution

• Enable order submit/cancel/modify for outcome assets using the documented action-asset encoding.

Rotation / refresh

Recurring predicted markets can rotate in two ways:

1. Recycled parameters: the tradable InstrumentId remains stable, but the expiry/threshold metadata changes after expiry.
2. Active outcome id changes: for categorical questions (e.g. priceBucket with 3 named outcomes) the active tradable outcomes may change to new outcome IDs each period.

Propose:

• An adapter-level configuration option to refresh outcome instrument definitions aligned to the next known expiry (rather than fixed-interval polling).
• A documented strategy pattern (and/or helper) to “select active instrument by key” and re-subscribe when the active InstrumentId changes.

Non-goals (initially)

• Historical quotes/trades for outcomes (if the venue doesn’t provide it).
• Guaranteeing deep liquidity / continuous quotes for outcomes.

Considerations

• Hyperliquid docs have historically labeled outcomeMeta as testnet-only; the integration should be opt-in and degrade gracefully if unavailable.
• Examples/tests should not assume outcome quotes always stream continuously.

References

• Hyperliquid docs: asset ids / outcomes encoding: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
• Hyperliquid docs: info endpoint lists outcomeMeta: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot
• QuickNode outcomeMeta reference (response includes outcomes[] and questions[]): https://www.quicknode.com/docs/hyperliquid/info-endpoints/outcomeMeta

[cjdsellers]

Hi @graceyangfan

Thanks for raising the RFC.

Per my comment on #4032, this is currently being worked on and will land in due course.

[cjdsellers]

Hi @graceyangfan,

Thanks for the detailed RFC. Just landed HIP-4 outcome support on develop. Worth flagging what's in, what's known limited, and what still wants work.

What landed

Instrument discovery via outcomeMeta, opt-in through HyperliquidProductType.OUTCOME. The InstrumentId scheme uses the venue's token form rather than your OUTCOME-{id}-{side}-OUTCOME proposal: Nautilus symbol is +{encoding}.HYPERLIQUID and raw_symbol is #{encoding} (what l2Book / allMids accept). Encoding is 10 * outcome + side and asset_id = 100_000_000 + encoding, matching the HL docs. Each outcome emits two BinaryOption instruments (Yes / No), denominated in USDH (token 360 on the USDH/USDC pair @230), with expiration_ns parsed from the description's expiry:YYYYMMDD-HHMM.

Market data subscriptions work via the existing l2Book, trades, and bbo channels.

spotClearinghouseState now surfaces outcome side tokens correctly: SpotBalance.token was tightened to Option<u32> (the venue omits it on +E coins), and request_spot_position_status_reports resolves +E / #E coins to their matching BinaryOption so HIP-4 holdings reconcile alongside spot.

Settlement dispatch: the Rust execution client periodically polls outcomeMeta, runs derive_outcome_settlements, and emits a synthetic position-closing FillReport (Sell at 1.0 USDH for winners, 0.0 for losers) for each newly-resolved pair that the account still holds. Configurable via outcome_settlement_poll_secs (default 60s, 0 disables). Idempotent within a session via OutcomeSettlementTracker.

Known limited: order placement

The venue requires a separate userOutcome action (splitOutcome, negateOutcome) to mint side-token pairs from quote tokens before orders can match. Buys on +E.HYPERLIQUID are rejected with Insufficient spot balance asset=100000{encoding} until the account holds the side tokens. The adapter wires only the standard order action, so order entry through Nautilus only works after an off-adapter splitOutcome (e.g. via the HL web UI). The full HIP-4 trading flow plus a strategy-level helper that bundles split + order is the next piece.

Outstanding

• userOutcome / splitOutcome / negateOutcome action implementations and a strategy-side surface for them.
• Settlement dispatch on the Python HyperliquidExecutionClient: today the Rust client owns the poll; the Python path through HyperliquidLiveExecClientFactory does not start it.
• Standalone priceBinary settlement detection: outcomes not referenced by any question (e.g. the recurring BTC daily binary) don't appear in settledNamedOutcomes, so resolution needs a separate signal such as settledOutcome. Not wired.
• Fallback-wins branch: when no named outcome resolves and the fallback wins, derive_outcome_settlements currently emits nothing.
• Cross-restart settlement tracker persistence: the tracker is in-process today.
• Historical outcome instrument resolution during recon: settled outcomes drop out of outcomeMeta, so mass-status fills on already-settled outcomes warn Instrument not found in cache.
• The expiry-aligned refresh helper you proposed for recurring markets.
• Multi-outcome priceBucket semantics beyond the named / fallback shapes.

Testing

Pure logic is covered: outcome asset id encoding, instrument modeling, spot balance reconcile for +E coins, settlement helper across winners / losers / fallback-loses, settlement fill construction (precision, identifiers, idempotency). Unit tests live under crates/adapters/hyperliquid/src/{common,http,outcome_settlement}.rs. Mock-server integration tests cover the dispatcher's outcome-filter routing.

Live mainnet test drive validated connect, account state with USDH, position recon for held side tokens, order submission round-trip up to the venue's splitOutcome rejection (which is the known limit above). Settlement dispatch couldn't fire end-to-end since the test account holds no settled positions. New live testers under examples/live/hyperliquid/hyperliquid_outcomes_exec_tester.py (Python) and the Rust equivalent node_outcome_exec_tester example.

Full breakdown in docs/integrations/hyperliquid.md under "HIP-4 outcome markets".

Please let me know how things go when/if you get a chance to test!

[graceyangfan]

Hi @cjdsellers,

Thanks for the detailed update. We haven't started live trading on HIP-4 outcome markets yet, but we plan to run paper trading strategies soon.

Here's what we expect to validate (and what we won't) during paper trading:

Can validate:

• Instrument discovery and data parsing (outcomeMeta, BinaryOption definitions, symbol mapping, expiration)
• Market data subscriptions (l2Book, trades, bbo)
• Strategy signal generation and order lifecycle flow (fills will be simulated by the sandbox engine)

Cannot validate:

• Real order submission and exchange responses (including the splitOutcome prerequisite you mentioned)
• Real account state and spot balance reconciliation (+E / #E coin mapping, USDH balances)
• Settlement dispatch and outcome resolution tracking (no real positions to settle)
• userOutcome / splitOutcome / negateOutcome actions

In short, we can verify the data and strategy plumbing, but not the execution, funding, and settlement paths that require real exchange interaction. We'll share feedback once we've run the data-path tests.

Best,

[cjdsellers]

Quick follow-up @graceyangfan,

Pushed e7073bc020 on develop which tightens the outcome IDs and exposes the venue metadata. The InstrumentId now matches your original RFC proposal more closely, and the parsed outcomeMeta description fields are surfaced on BinaryOption.info so strategies can branch on class / underlying / expiry / target_price etc. without reparsing.

No change to the outstanding items list - splitOutcome / negateOutcome, Python-side settlement dispatch, standalone priceBinary resolution, fallback-wins branch, cross-restart tracker persistence, and the expiry-aligned refresh helper are still open.

Going to close this RFC now that the scope is landed and tracked in the doc; please open separate scoped issues against the outstanding items as they come up for you.