> ## Documentation Index
> Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Prediction Markets (HIP-4)

> HIP-4 prediction market actions, settlement, and metadata enrichment

<Note>
  HIP-4 is live on **testnet**. When mainnet launches, hypernode will detect new markets within 60 seconds and start streaming prediction events automatically. No configuration needed.
</Note>

## Prediction actions in the stream

Five HIP-4 actions appear as pre-consensus events in the gossip stream:

| Type            | Description                               | Data                     |
| --------------- | ----------------------------------------- | ------------------------ |
| `userOutcome`   | Order on an outcome token                 | Outcome asset ID, amount |
| `splitOutcome`  | Split USDH into YES + NO tokens           | Outcome ID, amount       |
| `mergeOutcome`  | Merge YES + NO back into USDH             | Outcome ID, amount       |
| `negateOutcome` | Swap YES for NO (or vice versa)           | Outcome ID, amount       |
| `mergeQuestion` | Merge multi-outcome tokens back into USDH | Question ID, amount      |

### Confirmed events

Prediction orders and fills appear as regular confirmed events with `#` coin names:

```json theme={null}
{
  "type": "order",
  "consensus": "confirmed",
  "asset": "#40860",
  "data": {
    "coin": "#40860",
    "side": "B",
    "px": "0.40",
    "sz": "30.0",
    "status": "open",
    "prediction": {
      "outcome_id": 4086,
      "side_index": 0,
      "asset_id": 100040860
    }
  }
}
```

The `prediction` object is automatically enriched on every event with a `#` coin.

### Settlement events

When an outcome settles, fills appear with `dir: "Settlement"`:

```json theme={null}
{
  "type": "fill",
  "consensus": "confirmed",
  "asset": "#40861",
  "data": {
    "coin": "#40861",
    "px": "0.0",
    "side": "A",
    "dir": "Settlement",
    "closedPnl": "-10.4",
    "fee": "0.0",
    "feeToken": "USDH"
  }
}
```

* `px: "1.0"` = this side won (token redeemable for 1 USDH)
* `px: "0.0"` = this side lost (token worth nothing)
* `side: "A"` = auto-settlement (not a user trade)

## Subscribing to prediction events

**All prediction market activity:**

```json theme={null}
{
  "action": "subscribe",
  "filters": {
    "action_types": ["userOutcome", "splitOutcome", "mergeOutcome", "mergeQuestion", "negateOutcome"]
  }
}
```

**Track a specific outcome token:**

```json theme={null}
{
  "action": "subscribe",
  "filters": {"assets": ["#40860"]}
}
```

**Track settlements (filter confirmed fills, check for `dir: "Settlement"`):**

```json theme={null}
{
  "action": "subscribe",
  "filters": {"action_types": ["fill"], "assets": ["#40860"]}
}
```

## Metadata enrichment

Every prediction event is automatically enriched with metadata from outcomeMeta, refreshed every 60 seconds:

| Field                   | Type   | Description                       |
| ----------------------- | ------ | --------------------------------- |
| `prediction.outcome_id` | number | Outcome ID                        |
| `prediction.side_index` | number | 0 = Yes, 1 = No (or custom sides) |
| `prediction.asset_id`   | number | Full asset ID (100M + encoding)   |

The enriched prices endpoint adds more:

| Field                       | Description                             |
| --------------------------- | --------------------------------------- |
| `outcome_name`              | Human-readable name                     |
| `side_name`                 | "Yes", "No", or custom (e.g., "Hypurr") |
| `question`                  | Parent question name (multi-outcome)    |
| `price_binary.underlying`   | Underlying asset (e.g., "BTC")          |
| `price_binary.target_price` | Target price                            |
| `price_binary.expiry`       | Expiry timestamp                        |
| `price_binary.period`       | Roll period (e.g., "1d", "15m")         |

## Admin events

These appear when markets are created or settled:

| Type                       | Description                                                           |
| -------------------------- | --------------------------------------------------------------------- |
| `registerQuestion`         | New prediction question created                                       |
| `registerOutcome`          | New outcome added                                                     |
| `settleOutcome`            | Outcome resolved (triggers settlement fills)                          |
| `changeOutcomeDescription` | Outcome metadata updated (e.g., recurring market rolls to new expiry) |