> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/outcomes/settledoutcomes.md).

# settledOutcomes

Returns a list of recently settled prediction market outcomes, ordered by most recent first.

## POST Request

<table><thead><tr><th width="161">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"settledOutcomes"</code></td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max results to return, default 100, max 100 (optional)</td></tr><tr><td><code>kind</code></td><td>string</td><td><code>"price"</code> (default), <code>"canonical"</code>, or <code>"all"</code> — see <a href="#the-kind-filter">The kind filter</a> (optional)</td></tr><tr><td><code>name</code></td><td>string</td><td>Filter by outcome name (optional)</td></tr><tr><td><code>class</code></td><td>string</td><td>Filter by outcome class, e.g. <code>"priceBinary"</code> (optional)</td></tr><tr><td><code>underlying</code></td><td>string</td><td>Filter by underlying asset, e.g. <code>"HYPE"</code> (optional)</td></tr><tr><td><code>period</code></td><td>string</td><td>Filter by period, e.g. <code>"15m"</code> (optional)</td></tr><tr><td><code>category</code></td><td>string</td><td>Filter by canonical-market category, e.g. <code>"sports"</code>, case-insensitive (optional)</td></tr><tr><td><code>subCategory</code></td><td>string</td><td>Filter by canonical-market sub-category, case-insensitive (optional)</td></tr></tbody></table>

> By default (`kind` omitted) only structured price markets are returned. Pass `kind: "canonical"` for HIP-4 validator-voted (prose) markets, or `kind: "all"` for both. See [The kind filter](#the-kind-filter).

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "settledOutcomes",
    "limit": 10,
    "underlying": "HYPE"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'settledOutcomes',
        'limit': 10,
        'underlying': 'HYPE'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'settledOutcomes',
        limit: 10,
        underlying: 'HYPE'
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}
```

{% endtab %}
{% endtabs %}

***

## Response Fields

Returns an object with two arrays: `outcomes` (the settled outcome objects, sorted descending by `outcomeId`) and `questions` (the parent HIP-4 questions of any priceBucket children that appear in `outcomes`, sorted descending by `questionId`). Both arrays are always present, even when empty.

The `limit` and the filter parameters (`name`, `class`, `underlying`, `period`) apply to `outcomes` only. `questions` is derived from the resulting outcomes — a question is included if at least one of its children (named or fallback) is in the `outcomes` result. Practical implications: filtering by `class: "priceBinary"` yields priceBinary outcomes plus an empty `questions` array (standalone outcomes have no parent question); filtering by `class: "priceBucket"` yields priceBucket children plus their parent question(s).

### Outcome object

| Field            | Type    | Description                                                                                                                                                                            |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcomeId`      | integer | The outcome ID                                                                                                                                                                         |
| `kind`           | string  | `"price"` for structured markets, `"canonical"` for HIP-4 validator-voted (prose) markets                                                                                              |
| `name`           | string  | Outcome name from the register event                                                                                                                                                   |
| `description`    | string  | Pipe-separated description. priceBucket children copy this as-is from the parent question                                                                                              |
| `sideSpecs`      | array   | Side specifications, e.g. `[{"name":"Yes"},{"name":"No"}]`                                                                                                                             |
| `class`          | string? | `"priceBinary"` or `"priceBucket"`. `null` when `kind` is `"canonical"`                                                                                                                |
| `underlying`     | string? | Underlying asset, e.g. `"HYPE"`. `null` when `kind` is `"canonical"`                                                                                                                   |
| `expiry`         | string? | Expiry timestamp, e.g. `"20260508-1245"`. `null` when `kind` is `"canonical"`                                                                                                          |
| `targetPrice`    | string? | Numeric strike for `priceBinary`; bucket-range string for `priceBucket` (see [Target price formats](#target-price-formats) below). `null` when `kind` is `"canonical"`                 |
| `period`         | string? | Period, e.g. `"15m"`. `null` when `kind` is `"canonical"`                                                                                                                              |
| `category`       | string? | Canonical-market category, e.g. `"sports"`. `null` on price markets                                                                                                                    |
| `subCategory`    | string? | Canonical-market sub-category. `null` on price markets                                                                                                                                 |
| `quoteToken`     | string  | Quote token ID                                                                                                                                                                         |
| `yesAssetId`     | string  | YES-side asset ID, format `"#{outcomeId * 10}"`                                                                                                                                        |
| `noAssetId`      | string  | NO-side asset ID, format `"#{outcomeId * 10 + 1}"`                                                                                                                                     |
| `settleFraction` | string  | `"1"` if this outcome won, `"0"` otherwise. priceBucket children: exactly one named child has `"1"`; the fallback has `"1"` only when no named child wins                              |
| `settlePrice`    | string? | **Deprecated** alias of `settleDetails` for price markets (same numeric string); `null` on canonical markets. Will be removed in a future major version — read `settleDetails` instead |
| `settleDetails`  | string? | Settlement result: numeric settle price as a string for price markets (e.g. `"73336"`); freeform decision text for canonical markets                                                   |
| `yesStats`       | object  | YES-side market stats. Always present; zero-valued when no fills (see [Stats object](#stats-object) below)                                                                             |
| `noStats`        | object  | NO-side market stats                                                                                                                                                                   |

### Question object

Question entries appear when the response includes priceBucket children — each such child has a parent question grouping 3 named children plus one fallback child. Question fields:

| Field                 | Type              | Description                                                                                                                                     |
| --------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `questionId`          | integer           | The question ID (assigned by chain)                                                                                                             |
| `kind`                | string            | `"price"` or `"canonical"`                                                                                                                      |
| `name`                | string            | Question name                                                                                                                                   |
| `description`         | string            | Pipe-separated description; named children copy this as-is                                                                                      |
| `class`               | string?           | `"priceBucket"`. `null` when `kind` is `"canonical"`                                                                                            |
| `underlying`          | string?           | Underlying asset. `null` when `kind` is `"canonical"`                                                                                           |
| `expiry`              | string?           | Expiry timestamp. `null` when `kind` is `"canonical"`                                                                                           |
| `period`              | string?           | Period. `null` when `kind` is `"canonical"`                                                                                                     |
| `priceThresholds`     | string?           | Sorted comma-separated list of 2 cut-points. `null` when `kind` is `"canonical"`                                                                |
| `category`            | string?           | Canonical-market category. `null` on price questions                                                                                            |
| `subCategory`         | string?           | Canonical-market sub-category. `null` on price questions                                                                                        |
| `quoteToken`          | string            | Quote token ID                                                                                                                                  |
| `fallbackOutcome`     | integer           | `outcomeId` of the fallback child                                                                                                               |
| `fallbackName`        | string            | Name of the fallback child                                                                                                                      |
| `fallbackDescription` | string            | Description of the fallback child                                                                                                               |
| `namedOutcomes`       | array of integers | `outcomeId`s of the 3 named children, in named-index order                                                                                      |
| `winningOutcome`      | integer?          | `outcomeId` of the child that resolved YES (a named child, or the fallback if all named children resolve NO). `null` until the question settles |
| `winningNamedIndex`   | integer?          | Position in `namedOutcomes` of the winner if a named child won, `null` if the fallback won (or unsettled)                                       |
| `settlePrice`         | string?           | **Deprecated** alias of `settleDetails` for price questions; `null` on canonical questions. Read `settleDetails` instead                        |
| `settleDetails`       | string?           | Numeric settle price for price questions; freeform decision text for canonical questions                                                        |
| `time`                | integer           | Settlement timestamp (ms)                                                                                                                       |
| `stats`               | object            | Aggregate trading stats across the question's children. Always present; zero-valued when no fills. See [Stats object](#stats-object) below.     |

### Target price formats

The `targetPrice` field on each outcome is a string whose format depends on the outcome's `class`.

**`priceBinary`** — a single numeric strike. The outcome resolves YES if the underlying's settle price meets the strike, NO otherwise.

```
"targetPrice": "52.328"
```

**`priceBucket`** — outcomes belong to a parent question that defines `priceThresholds` (a sorted comma-separated list of 2 cut-points splitting the price line into 3 buckets). The question has 3 named children plus one fallback child. Each named child resolves YES if the settle price falls in its bucket; the fallback child resolves YES if all named children resolve NO. The format mirrors interval notation:

| Child role                     | `targetPrice` value | Example (thresholds `80828, 81071`) |
| ------------------------------ | ------------------- | ----------------------------------- |
| First named child (index `0`)  | `<t0`               | `<80828`                            |
| Middle named child (index `1`) | `[t0,t1)`           | `[80828,81071)`                     |
| Last named child (index `2`)   | `>=t1`              | `>=81071`                           |
| Fallback child                 | raw threshold list  | `80828,81071`                       |

The fallback's literal comma-separated value signals "any price not covered by a named child" rather than a specific range. Use the parent question's `priceThresholds` field if you need to render the fallback's range yourself.

### Stats object

All fields except `settlementClosedPnl` reflect orderbook trading only. Fills with `dir = "Settlement"` (auto-close fills produced when the outcome settles, at price 1 for the winning side and 0 for the losing side) are excluded so vwap, lastPrice, min/max, largestTrade, and avg/median trade notional aren't distorted by them. `settlementClosedPnl` summarises the realized PnL across those Settlement-direction fills for the side.

| Field                 | Type    | Description                                                         |
| --------------------- | ------- | ------------------------------------------------------------------- |
| `coin`                | string  | Asset ID for this side                                              |
| `trades`              | integer | Number of orderbook fills                                           |
| `uniqueTraders`       | integer | Distinct users that traded this side                                |
| `volumeNotional`      | string  | Sum of `px * sz` across orderbook fills                             |
| `volumeContracts`     | string  | Sum of `sz` across orderbook fills                                  |
| `lastPrice`           | string  | Price of the most recent orderbook fill                             |
| `vwap`                | number  | Volume-weighted average orderbook price                             |
| `minPrice`            | string  | Minimum orderbook fill price                                        |
| `maxPrice`            | string  | Maximum orderbook fill price                                        |
| `avgTradeNotional`    | number  | Mean `px * sz` across orderbook fills                               |
| `medianTradeNotional` | number  | Median `px * sz` across orderbook fills                             |
| `largestTrade`        | string  | Maximum `px * sz` of any orderbook fill                             |
| `firstTrade`          | integer | Timestamp (ms) of earliest orderbook fill                           |
| `lastTrade`           | integer | Timestamp (ms) of latest orderbook fill                             |
| `settlementClosedPnl` | string  | Sum of `closed_pnl` across Settlement-direction fills for this side |

#### Question stats object

Question stats are intentionally trimmed compared to outcome stats. Price-shaped metrics (`lastPrice`, `vwap`, `minPrice`, `maxPrice`, `largestTrade`, `avgTradeNotional`, `medianTradeNotional`) don't aggregate cleanly across the children's YES + NO assets, so they aren't reported. There's no `coin` field — questions don't own a single asset. Settlement and the four HIP-4 conversion ops (`Split Outcome`, `Negate Outcome`, `Merge Outcome`, `Merge Question`) are excluded from all metrics.

| Field             | Type    | Description                                                                                                                                                          |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trades`          | integer | Number of orderbook matches across all child YES + NO assets. Counts each chain match exactly once (filters to `dir = 'Buy'`; every match emits one Buy + one Sell). |
| `uniqueTraders`   | integer | Distinct users that traded any child asset (Buy or Sell).                                                                                                            |
| `volumeNotional`  | string  | Sum of `px * sz` across `dir = 'Buy'` fills on any child.                                                                                                            |
| `volumeContracts` | string  | Sum of `sz` across `dir = 'Buy'` fills on any child.                                                                                                                 |
| `firstTrade`      | integer | Timestamp (ms) of the earliest orderbook fill on any child.                                                                                                          |
| `lastTrade`       | integer | Timestamp (ms) of the latest orderbook fill on any child.                                                                                                            |

<details>

<summary>Response</summary>

The example covers three settled outcomes — a named priceBucket child (`7604`), the fallback child of the same question (`7601`), and a standalone priceBinary outcome (`7600`) — all with `settleFraction: "0"` (`"0"` for losers, `"1"` for the winner). Question `302`'s actual winner is `7603`, surfaced in the question's `winningOutcome` field; the question itself is automatically derived into `questions` because its child `7604` appears in `outcomes`.

```json
{
  "outcomes": [
    {
      "outcomeId": 7604,
      "kind": "price",
      "name": "Recurring Named Outcome",
      "description": "class:priceBucket|underlying:BTC|expiry:20260508-1245|priceThresholds:80518,80760|period:15m",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260508-1245",
      "targetPrice": ">=80760",
      "period": "15m",
      "category": null,
      "subCategory": null,
      "quoteToken": "1452",
      "yesAssetId": "#76040",
      "noAssetId": "#76041",
      "settleFraction": "0",
      "settlePrice": "80547.9",
      "settleDetails": "80547.9",
      "yesStats": { "coin": "#76040", "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "lastPrice": "0", "vwap": 0.0, "minPrice": "0", "maxPrice": "0", "avgTradeNotional": 0.0, "medianTradeNotional": 0.0, "largestTrade": "0", "firstTrade": 0, "lastTrade": 0, "settlementClosedPnl": "0" },
      "noStats":  { "coin": "#76041", "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "lastPrice": "0", "vwap": 0.0, "minPrice": "0", "maxPrice": "0", "avgTradeNotional": 0.0, "medianTradeNotional": 0.0, "largestTrade": "0", "firstTrade": 0, "lastTrade": 0, "settlementClosedPnl": "0" }
    },
    {
      "outcomeId": 7601,
      "kind": "price",
      "name": "Recurring Fallback",
      "description": "class:priceBucket|underlying:BTC|expiry:20260508-1245|priceThresholds:80518,80760|period:15m",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260508-1245",
      "targetPrice": "80518,80760",
      "period": "15m",
      "category": null,
      "subCategory": null,
      "quoteToken": "1452",
      "yesAssetId": "#76010",
      "noAssetId": "#76011",
      "settleFraction": "0",
      "settlePrice": "80547.9",
      "settleDetails": "80547.9",
      "yesStats": { "coin": "#76010", "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "lastPrice": "0", "vwap": 0.0, "minPrice": "0", "maxPrice": "0", "avgTradeNotional": 0.0, "medianTradeNotional": 0.0, "largestTrade": "0", "firstTrade": 0, "lastTrade": 0, "settlementClosedPnl": "0" },
      "noStats":  { "coin": "#76011", "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "lastPrice": "0", "vwap": 0.0, "minPrice": "0", "maxPrice": "0", "avgTradeNotional": 0.0, "medianTradeNotional": 0.0, "largestTrade": "0", "firstTrade": 0, "lastTrade": 0, "settlementClosedPnl": "0" }
    },
    {
      "outcomeId": 7600,
      "kind": "price",
      "name": "Recurring",
      "description": "class:priceBinary|underlying:HYPE|expiry:20260508-1245|targetPrice:28.52|period:15m",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBinary",
      "underlying": "HYPE",
      "expiry": "20260508-1245",
      "targetPrice": "28.52",
      "period": "15m",
      "category": null,
      "subCategory": null,
      "quoteToken": "1452",
      "yesAssetId": "#76000",
      "noAssetId": "#76001",
      "settleFraction": "0",
      "settlePrice": "28.52",
      "settleDetails": "28.52",
      "yesStats": { "coin": "#76000", "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "lastPrice": "0", "vwap": 0.0, "minPrice": "0", "maxPrice": "0", "avgTradeNotional": 0.0, "medianTradeNotional": 0.0, "largestTrade": "0", "firstTrade": 0, "lastTrade": 0, "settlementClosedPnl": "0" },
      "noStats":  { "coin": "#76001", "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "lastPrice": "0", "vwap": 0.0, "minPrice": "0", "maxPrice": "0", "avgTradeNotional": 0.0, "medianTradeNotional": 0.0, "largestTrade": "0", "firstTrade": 0, "lastTrade": 0, "settlementClosedPnl": "0" }
    }
  ],
  "questions": [
    {
      "questionId": 302,
      "kind": "price",
      "name": "Recurring",
      "description": "class:priceBucket|underlying:BTC|expiry:20260508-1245|priceThresholds:80518,80760|period:15m",
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260508-1245",
      "period": "15m",
      "priceThresholds": "80518,80760",
      "category": null,
      "subCategory": null,
      "quoteToken": "1452",
      "fallbackOutcome": 7601,
      "fallbackName": "Recurring Fallback",
      "fallbackDescription": "other",
      "namedOutcomes": [7602, 7603, 7604],
      "winningOutcome": 7603,
      "winningNamedIndex": 1,
      "settlePrice": "80547.9",
      "settleDetails": "80547.9",
      "time": 1778244305560,
      "stats": { "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "firstTrade": 0, "lastTrade": 0 }
    }
  ]
}
```

</details>

***

## The kind filter

A single optional `kind` request field selects which markets are returned:

| `kind`              | Returns                                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `"price"` (default) | Structured price markets only (`priceBinary` / `priceBucket`). Reproduces the original endpoint behaviour for callers that omit `kind`. |
| `"canonical"`       | HIP-4 validator-voted (prose) markets only.                                                                                             |
| `"all"`             | Both kinds in one `outcomes` / `questions` envelope.                                                                                    |

The response shape is identical regardless of `kind` — the same `outcomes` / `questions` envelope, sort order, stats objects, and `limit` semantics. Each row carries a `kind` field telling you which it is.

**Nullability by kind.** On a `kind: "price"` response the structured fields (`class`, `underlying`, `expiry`, `targetPrice`, `period`) are always populated and `category` / `subCategory` are `null`. On a `kind: "canonical"` response those structured fields are `null` and `category` / `subCategory` are populated. A `kind: "all"` response mixes both, so treat every structured field as nullable and branch on `kind`.

**Settlement field.** Read `settleDetails` — it carries the numeric settle price for price markets and the freeform decision text for canonical markets. `settlePrice` is a deprecated alias kept for backward compatibility (equal to `settleDetails` on price markets, `null` on canonical) and will be removed in a future major version.