Module parse 

Parsing utilities that convert Hyperliquid payloads into Nautilus domain models.

Conditional Order Support

This module implements conditional order support for Hyperliquid.

Supported Order Types

Standard Orders

• Market: Implemented as IOC (Immediate-or-Cancel) limit orders.
• Limit: Standard limit orders with GTC/IOC/ALO time-in-force.

Conditional/Trigger Orders

• StopMarket: Protective stop that triggers at specified price and executes at market.
• StopLimit: Protective stop that triggers at specified price and executes at limit.
• MarketIfTouched: Profit-taking/entry order that triggers and executes at market.
• LimitIfTouched: Profit-taking/entry order that triggers and executes at limit.

Order Semantics

Stop Orders (StopMarket/StopLimit)

• Used for protective stops and risk management.
• Mapped to Hyperliquid’s trigger orders with tpsl: Sl.
• Trigger when price reaches the stop level.
• Execute immediately (market) or at limit price.

If Touched Orders (MarketIfTouched/LimitIfTouched)

• Used for profit-taking or entry orders.
• Mapped to Hyperliquid’s trigger orders with tpsl: Tp.
• Trigger when price reaches the target level.
• Execute immediately (market) or at limit price.

Trigger Price Logic

The tpsl field (Take Profit / Stop Loss) is determined by:

1. Order Type: Stop orders → SL, If Touched orders → TP
2. Price Relationship (if available):
   • For BUY orders: trigger above market → SL, below → TP
   • For SELL orders: trigger below market → SL, above → TP

Trigger Type Support

Hyperliquid uses mark price for all trigger evaluations (TP/SL orders).

Constants

DEFAULT_MARKET_SLIPPAGE_BPS

Default slippage buffer in basis points for MARKET orders.

OUTCOME_SIDE_NO

No-side label on Nautilus outcome symbols.

OUTCOME_SIDE_YES

Yes-side label on Nautilus outcome symbols.

OUTCOME_SYMBOL_SUFFIX

Suffix shared by every Nautilus outcome symbol, mirroring -PERP / -SPOT.

Functions

bar_type_to_interval

Converts a Nautilus BarType to a Hyperliquid bar interval.

cache_alias_for_symbol

Returns the secondary cache-alias key for a Nautilus instrument symbol.

clamp_price_to_precision

Clamp a price to the instrument’s decimal precision, rounding in the direction that preserves the slippage buffer.

client_order_id_to_cancel_request_with_asset

Converts a client order ID to a Hyperliquid cancel request using a pre-resolved asset index.

derive_limit_from_trigger

Derives a limit price from a trigger price with a configurable slippage buffer in basis points, widening the limit so BUY satisfies limit_px >= trigger_px and SELL satisfies limit_px <= trigger_px.

derive_market_order_price

Derives a market order limit price from a quote with a configurable slippage buffer in basis points, rounded to 5 significant figures and clamped to the instrument’s price precision.

deserialize_decimal_from_str

Deserializes a Decimal from a JSON string.

deserialize_optional_decimal_from_str

Deserializes an optional Decimal from a string-only field.

deserialize_vec_decimal_from_str

Deserializes a Vec<Decimal> from a JSON array of strings.

ensure_min_notional

Ensure the notional value meets minimum requirements.

extract_error_message

Extracts error message from a Hyperliquid exchange response.

extract_inner_error

Extracts per-item error from a successful Hyperliquid exchange response.

extract_inner_errors

Extracts per-item errors from a successful batch response.

format_outcome_nautilus_symbol

Formats an (outcome_index, side) pair into the Nautilus outcome symbol form {outcome_index}-{YES|NO}-OUTCOME.

format_trailing_stop_info

Converts WebSocket trailing stop data to description string.

is_conditional_order_data

Determines if an order is a conditional/trigger order based on order data.

make_fill_trade_id

Creates a deterministic [TradeId] from fill fields common to both WS and HTTP responses.

millis_to_nanos

Converts millisecond timestamp to [UnixNanos].

normalize_order

Complete normalization for an order including price, quantity, and notional validation

normalize_price

Normalize price to the specified number of decimal places.

normalize_quantity

Normalize quantity to the specified number of decimal places.

order_to_hyperliquid_request_with_asset

Converts a Nautilus order to Hyperliquid request using a pre-resolved asset index.

order_to_hyperliquid_request_with_asset_and_cloid

Converts a Nautilus order to Hyperliquid request with an explicit CLOID.

outcome_token_from_nautilus_symbol

Returns the +<encoding> token form for the side token referenced by a Nautilus outcome symbol, or None if the symbol is not an outcome.

parse_account_balances_and_margins

Parses Hyperliquid clearinghouse state into Nautilus account balances and margins.

parse_combined_account_balances_and_margins

Merges perp clearinghouse balances with spot balances into a unified set.

parse_order_status_with_trigger

Extracts order status from WebSocket order data.

parse_outcome_nautilus_symbol

Parses a Nautilus outcome instrument symbol of the form {outcome_index}-{YES|NO}-OUTCOME into (outcome_index, side) where side is 0 for Yes and 1 for No.

parse_outcome_symbol

Parses an outcome (HIP-4) spot coin or token symbol into an asset ID.

parse_spot_account_balances

Parses Hyperliquid spot clearinghouse state into Nautilus account balances.

parse_trigger_order_type

Parses trigger order type from Hyperliquid order data.

parse_trigger_order_type_label

Parses trigger semantics from a REST orderType label.

parse_trigger_price

Parses trigger price from string to Decimal.

round_down_to_step

Round quantity down to the nearest valid step size.

round_down_to_tick

Round price down to the nearest valid tick size.

round_to_sig_figs

Round a decimal to at most N significant figures. Hyperliquid requires prices to have at most 5 significant figures.

serialize_decimal_as_str

Serializes a Decimal as a string (lossless, no scientific notation).

serialize_optional_decimal_as_str

Serializes an optional Decimal as a string.

serialize_vec_decimal_as_str

Serializes a Vec<Decimal> as an array of strings.

time_in_force_to_hyperliquid_tif

Converts a Nautilus TimeInForce to Hyperliquid TIF.

validate_conditional_order_params

Validates conditional order parameters from WebSocket data.