Skip to navigation
Direct trading

Outcome-token conversions

Outcome conversions are signed actions with action.type: "userOutcome", posted to Predict like any other trading write. All four share one type on chain, so each has a path of its own and the path and the nested action have to agree.

PathNested actionConversion
POST /v1/trading/positions/splitsplitOutcomeX quote tokens into X shares of side 0 and side 1
POST /v1/trading/positions/mergemergeOutcomeEqual shares of both sides into quote tokens
POST /v1/trading/questions/{question_id}/mergemergeQuestionX Yes shares from every named outcome in one question into X quote tokens
POST /v1/trading/positions/negatenegateOutcomeX No shares of one question outcome into X Yes shares of every other named outcome

mergeOutcome.amount and mergeQuestion.amount accept null to use the maximum available amount. Split and negate require an explicit amount.

Questions

A question links mutually exclusive outcomes. Use Predict’s hl_question_id for question-level conversions. The question ID never replaces the order asset ID.

{question_id} in the merge path is that same Hyperliquid question ID, and it has to match mergeQuestion.question inside the signed action. A mismatch is a 400: the signed value is the one that would take effect, so a disagreement is a bug worth failing rather than quietly honouring.

Conversions change balances and should be signed with the same care as orders. Read spotClearinghouseState after the action and reconcile the corresponding ledger update before showing the conversion as final.

At settlement, side 0 automatically converts to the settlement fraction in quote tokens per share and side 1 converts to 1 - fraction. Read Predict’s outcome status and hl_settle_fraction for the authoritative catalog value.