> Use the canonical URL for citations. For the complete Predict API documentation index, fetch https://docs.staging.trypredict.com/llms.txt.

# Outcome-token conversions

> Learn how to split, merge, and negate Predict outcome tokens through the Predict trading API's signed userOutcome actions for standalone and mutually exclusive markets.

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.

| Path                                             | Nested action   | Conversion                                                                             |
| ------------------------------------------------ | --------------- | -------------------------------------------------------------------------------------- |
| `POST /v1/trading/positions/split`               | `splitOutcome`  | `X` quote tokens into `X` shares of side 0 and side 1                                  |
| `POST /v1/trading/positions/merge`               | `mergeOutcome`  | Equal shares of both sides into quote tokens                                           |
| `POST /v1/trading/questions/{question_id}/merge` | `mergeQuestion` | `X` Yes shares from every named outcome in one question into `X` quote tokens          |
| `POST /v1/trading/positions/negate`              | `negateOutcome` | `X` 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.