# settledOutcomesById

Returns metadata and stats for one or more settled prediction market outcomes.

## 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>"settledOutcomesById"</code></td></tr><tr><td><code>outcome_ids</code></td><td>integer[]</td><td>Array of outcome IDs (optional)</td></tr><tr><td><code>asset_ids</code></td><td>string[]</td><td>Array of asset IDs prefixed with <code>#</code>, e.g. <code>"#90"</code> (optional)</td></tr><tr><td><code>question_ids</code></td><td>integer[]</td><td>Array of HIP-4 question IDs (optional). Each question is server-side-expanded to its child outcomes (named + fallback), which appear in <code>outcomes</code>. The question itself appears in <code>questions</code>.</td></tr></tbody></table>

At least one of `outcome_ids`, `asset_ids`, or `question_ids` must be provided and non-empty. They can be combined — the results are merged and deduplicated. The combined number of unique IDs must not exceed 50.

Filtering by `outcome_ids` or `asset_ids` for a child of a question also surfaces the parent question in the `questions` array, so a single child lookup always returns its enclosing question.

{% 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": "settledOutcomesById",
    "outcome_ids": [9],
    "asset_ids": ["#30800"]
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'settledOutcomesById',
        'outcome_ids': [9],
        'asset_ids': ['#30800']
    },
    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: 'settledOutcomesById',
        outcome_ids: [9],
        asset_ids: ['#30800']
    }, {
        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` (matched settled outcome objects, sorted descending by `outcomeId`) and `questions` (the parent HIP-4 questions of any priceBucket children that appear in `outcomes`, plus any explicitly-requested `question_ids`, sorted descending by `questionId`). Both arrays are always present, even when empty.

### 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.

### Outcome object

| Field            | Type    | Description                                                                                                                                               |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcomeId`      | integer | The outcome ID                                                                                                                                            |
| `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"`, `"priceBucket"`, or null for legacy outcomes that predate the class tagging                                                              |
| `underlying`     | string? | Underlying asset, e.g. `"HYPE"`                                                                                                                           |
| `expiry`         | string? | Expiry timestamp                                                                                                                                          |
| `targetPrice`    | string? | Numeric strike for `priceBinary`; bucket-range string for `priceBucket` (see [Target price formats](#target-price-formats) above)                         |
| `period`         | string? | Period                                                                                                                                                    |
| `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? | Underlying settle price at the time of settlement                                                                                                         |
| `yesStats`       | object  | YES-side market stats; zero-valued when no fills (see [Stats object](#stats-object) below)                                                                |
| `noStats`        | object  | NO-side market stats                                                                                                                                      |

### Question object

| Field                 | Type              | Description                                                                                                                                 |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `questionId`          | integer           | The question ID (assigned by chain)                                                                                                         |
| `name`                | string            | Question name                                                                                                                               |
| `description`         | string            | Pipe-separated description; named children copy this as-is                                                                                  |
| `class`               | string            | Always `"priceBucket"`                                                                                                                      |
| `underlying`          | string            | Underlying asset                                                                                                                            |
| `expiry`              | string            | Expiry timestamp                                                                                                                            |
| `period`              | string            | Period                                                                                                                                      |
| `priceThresholds`     | string            | Sorted comma-separated list of 2 cut-points                                                                                                 |
| `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)                                |
| `winningNamedIndex`   | integer?          | Position in `namedOutcomes` of the winner if a named child won, `null` if the fallback won                                                  |
| `settlePrice`         | string?           | Underlying settle price at the time of settlement                                                                                           |
| `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. |

### 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>

Example for `{"question_ids": [302]}` — a settled HIP-4 question with three named children plus its fallback. The middle named child (`outcomeId: 7603`, `targetPrice: "[80518,80760)"`) won (`settleFraction: "1"`); the others have `settleFraction: "0"`. The question's `winningOutcome` and `winningNamedIndex` point at the winner.

```json
{
  "outcomes": [
    {
      "outcomeId": 7604,
      "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",
      "quoteToken": "1452",
      "yesAssetId": "#76040",
      "noAssetId": "#76041",
      "settleFraction": "0",
      "settlePrice": "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": 7603,
      "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": "[80518,80760)",
      "period": "15m",
      "quoteToken": "1452",
      "yesAssetId": "#76030",
      "noAssetId": "#76031",
      "settleFraction": "1",
      "settlePrice": "80547.9",
      "yesStats": { "coin": "#76030", "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": "#76031", "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": 7602,
      "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": "<80518",
      "period": "15m",
      "quoteToken": "1452",
      "yesAssetId": "#76020",
      "noAssetId": "#76021",
      "settleFraction": "0",
      "settlePrice": "80547.9",
      "yesStats": { "coin": "#76020", "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": "#76021", "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,
      "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",
      "quoteToken": "1452",
      "yesAssetId": "#76010",
      "noAssetId": "#76011",
      "settleFraction": "0",
      "settlePrice": "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" }
    }
  ],
  "questions": [
    {
      "questionId": 302,
      "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",
      "quoteToken": "1452",
      "fallbackOutcome": 7601,
      "fallbackName": "Recurring Fallback",
      "fallbackDescription": "other",
      "namedOutcomes": [7602, 7603, 7604],
      "winningOutcome": 7603,
      "winningNamedIndex": 1,
      "settlePrice": "80547.9",
      "time": 1778244305560,
      "stats": { "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "firstTrade": 0, "lastTrade": 0 }
    }
  ]
}
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/readme/rest-api/outcomes/settledoutcomesbyid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.