> 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/registeredoutcomes.md).

# registeredOutcomes

Get recent registered prediction market outcomes.

Returns a list of recently registered prediction market outcomes that have not yet been settled, 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>"registeredOutcomes"</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>"all"</code> (default), <code>"price"</code>, or <code>"canonical"</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, 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><tr><td><code>search</code></td><td>string</td><td>Free-text search across name, description, category and subCategory — see <a href="#free-text-search">Free-text search</a> (optional)</td></tr><tr><td><code>venue</code></td><td>string</td><td>Only outcomes deployed by this permissionless venue, e.g. <code>"skew"</code>. 2–4 ASCII letters, case-insensitive (optional)</td></tr><tr><td><code>deployedBy</code></td><td>string</td><td><code>"all"</code> (default), <code>"validator"</code> (registered by validator quorum, no venue), or <code>"venue"</code> (any permissionless venue) (optional)</td></tr></tbody></table>

> By default (`kind` omitted) all outcome kinds are returned. Pass `kind: "price"` for structured price markets only, or `kind: "canonical"` for HIP-4 prose markets only. 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": "registeredOutcomes",
    "limit": 10,
    "underlying": "HYPE"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'registeredOutcomes',
        '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: 'registeredOutcomes',
        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 %}

Only outcomes deployed by the `skew` venue, then only validator-deployed outcomes:

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "registeredOutcomes", "kind": "all", "venue": "skew"}'

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "registeredOutcomes", "kind": "all", "deployedBy": "validator"}'
```

***

## Response Fields

Returns an object with two arrays: `outcomes` (the registered 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`, `search`) 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 (\`class:...                                                                                                                                |
| `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-1300"`. `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. `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}"`                                                                                                                     |
| `yesStats`         | object  | Market stats for the YES side. Always present; zero-valued when no fills (see [Stats object](#stats-object) below)                                                     |
| `noStats`          | object  | Market stats for the NO side                                                                                                                                           |
| `deployerAddress`  | string? | Permissionless-venue deployer address; null on validator-registered outcomes                                                                                           |
| `deployerVenue`    | string? | Permissionless venue name (see `outcomeMeta.deployers`); null on validator-registered outcomes                                                                         |
| `deployerFeeScale` | string? | Multiplier applied to the deployer fee for this market, e.g. `"10"`. `null` on validator-registered outcomes and when the chain uses its default scale of 1            |

### 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 named children still open, in named-index order. A child that settles moves to `settledNamedOutcomes`                                          |
| `settledNamedOutcomes` | array of integers | `outcomeId`s of named children already settled. Disjoint from `namedOutcomes`, matching `outcomeMeta`. A question can have settled children while it is still open |
| `stats`                | object            | Aggregate trading stats across the question's children. Always present; zero-valued when no fills. See [Stats object](#stats-object) below.                        |
| `deployerAddress`      | string?           | Permissionless-venue deployer address; null on validator-registered questions                                                                                      |
| `deployerVenue`        | string?           | Permissionless venue name; null on validator-registered questions                                                                                                  |
| `deployerFeeScale`     | string?           | Multiplier applied to the deployer fee, e.g. `"10"`. `null` on validator-registered questions and when the chain uses its default scale of 1                       |

### Stats object

All stats fields reflect orderbook trading. The object is always emitted — when there are no fills, every numeric field is zero and timestamps are `0`.

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

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

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

<details>

<summary>Response</summary>

The example covers a priceBucket child (`outcomeId: 7609`), the corresponding fallback child (`7606`), a standalone priceBinary outcome (`7605`), and a child of a different question (`7470`) — plus both parent questions. Question `275` shows non-zero stats (16 fills); question `303` shows the zero-state.

```json
{
  "outcomes": [
    {
      "outcomeId": 7609,
      "name": "Recurring Named Outcome",
      "description": "class:priceBucket|underlying:BTC|expiry:20260508-1300|priceThresholds:80425,80666|period:15m",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260508-1300",
      "targetPrice": ">=80666",
      "period": "15m",
      "quoteToken": "1452",
      "yesAssetId": "#76090",
      "noAssetId": "#76091",
      "yesStats": {
        "coin": "#76090", "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
      },
      "noStats": {
        "coin": "#76091", "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
      }
    },
    {
      "outcomeId": 7606,
      "name": "Recurring Fallback",
      "description": "class:priceBucket|underlying:BTC|expiry:20260508-1300|priceThresholds:80425,80666|period:15m",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260508-1300",
      "targetPrice": "80425,80666",
      "period": "15m",
      "quoteToken": "1452",
      "yesAssetId": "#76060",
      "noAssetId": "#76061",
      "yesStats": { "coin": "#76060", "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 },
      "noStats":  { "coin": "#76061", "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 }
    },
    {
      "outcomeId": 7605,
      "name": "Recurring",
      "description": "class:priceBinary|underlying:HYPE|expiry:20260508-1300|targetPrice:28.52|period:15m",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBinary",
      "underlying": "HYPE",
      "expiry": "20260508-1300",
      "targetPrice": "28.52",
      "period": "15m",
      "quoteToken": "1452",
      "yesAssetId": "#76050",
      "noAssetId": "#76051",
      "yesStats": { "coin": "#76050", "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 },
      "noStats":  { "coin": "#76051", "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 }
    },
    {
      "outcomeId": 7470,
      "name": "Recurring Named Outcome",
      "description": "class:priceBucket|underlying:BTC|expiry:20260509-0600|priceThresholds:78342,81539|period:1d",
      "sideSpecs": [{"name": "Yes"}, {"name": "No"}],
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260509-0600",
      "targetPrice": ">=81539",
      "period": "1d",
      "quoteToken": "1452",
      "yesAssetId": "#74700",
      "noAssetId": "#74701",
      "yesStats": { "coin": "#74700", "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 },
      "noStats":  { "coin": "#74701", "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 }
    }
  ],
  "questions": [
    {
      "questionId": 303,
      "name": "Recurring",
      "description": "class:priceBucket|underlying:BTC|expiry:20260508-1300|priceThresholds:80425,80666|period:15m",
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260508-1300",
      "period": "15m",
      "priceThresholds": "80425,80666",
      "quoteToken": "1452",
      "fallbackOutcome": 7606,
      "fallbackName": "Recurring Fallback",
      "fallbackDescription": "other",
      "namedOutcomes": [7607, 7608, 7609],
      "settledNamedOutcomes": [],
      "stats": { "trades": 0, "uniqueTraders": 0, "volumeNotional": "0", "volumeContracts": "0", "firstTrade": 0, "lastTrade": 0 }
    },
    {
      "questionId": 275,
      "name": "Recurring",
      "description": "class:priceBucket|underlying:BTC|expiry:20260509-0600|priceThresholds:78342,81539|period:1d",
      "class": "priceBucket",
      "underlying": "BTC",
      "expiry": "20260509-0600",
      "period": "1d",
      "priceThresholds": "78342,81539",
      "quoteToken": "1452",
      "fallbackOutcome": 7467,
      "fallbackName": "Recurring Fallback",
      "fallbackDescription": "other",
      "namedOutcomes": [7468, 7469, 7470],
      "settledNamedOutcomes": [],
      "stats": {
        "trades": 16, "uniqueTraders": 2,
        "volumeNotional": "7799.98", "volumeContracts": "14000.00",
        "firstTrade": 1778222714885, "lastTrade": 1778223020033
      }
    }
  ]
}
```

</details>

***

## Free-text search

The optional `search` field matches case-insensitively against `name`, `description`, `category` and `subCategory`, combining with every other filter. A row matches when the whole query appears as a substring of one of those fields, or when every word of the query matches some word of a field:

* exactly, or
* as a prefix (for query words of at least 4 characters), or
* within a spelling-error budget (Damerau-Levenshtein distance): words of 5–8 characters allow 1 error, 9 or more allow 2. Words of up to 4 characters get no error budget — tickers and venue codes like `BTC` never near-match.

Examples: `"world cup"` matches `World Cup Final: Spain vs Argentina`; so do `"wolrd cup"` (typo) and `"spain argent"` (partial words, any order). `"BTX"` does not match `BTC`. Result order and `limit` semantics are unchanged.

## The kind filter

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

| `kind`            | Returns                                              |
| ----------------- | ---------------------------------------------------- |
| `"all"` (default) | Both kinds in one `outcomes` / `questions` envelope. |
| `"price"`         | Structured price markets only.                       |
| `"canonical"`     | HIP-4 validator-voted (prose) markets only.          |

The response shape is identical regardless of `kind`; 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`.