> 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/registeredoutcomesbyid.md). # registeredOutcomesById Returns metadata and stats for one or more registered prediction market outcomes that have not yet been settled. Each object consists of metadata and stats. ## POST Request
FieldTypeDescription
typestringMust be "registeredOutcomesById"
kindstring"all" (default for by-id), "price", or "canonical" — see The kind filter (optional)
outcome_idsinteger[]Array of outcome IDs (optional)
asset_idsstring[]Array of asset IDs prefixed with #, e.g. "#36360" (optional)
question_idsinteger[]Array of HIP-4 question IDs (optional). Each question is server-side-expanded to its child outcomes (named + fallback), which appear in outcomes. The question itself appears in questions.
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 100. 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. > By default (`kind` omitted) **all** requested ids are returned regardless of market type — a by-id lookup names exact rows, so it doesn't apply the list endpoints' price default. Pass `kind: "price"` to restrict to structured markets, or `kind: "canonical"` for HIP-4 validator-voted (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": "registeredOutcomesById", "outcome_ids": [3616], "asset_ids": ["#36170"] }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import os response = requests.post( 'https://api.hydromancer.xyz/info', json={ 'type': 'registeredOutcomesById', 'outcome_ids': [3616], 'asset_ids': ['#36170'] }, 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: 'registeredOutcomesById', outcome_ids: [3616], asset_ids: ['#36170'] }, { 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 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. ### 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-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 | ### Question object | 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 | | `settledNamedOutcomes` | array of integers | `outcomeId`s of named children already settled (empty for unsettled questions) | | `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 | 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`) | `=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.
Response Example for `{"outcome_ids": [7605, 7609]}`. `7605` is a standalone priceBinary outcome; `7609` is a priceBucket child whose parent question (`303`) is automatically derived into `questions`. ```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": 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 } } ], "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 } } ] } ```
*** ## The kind filter The optional `kind` request field controls which of the requested ids are returned: `"all"` (the by-id default) returns every requested id regardless of type, `"price"` only structured markets, `"canonical"` only HIP-4 validator-voted (prose) markets. An id whose market doesn't match `kind` is omitted from the response. Each returned row carries a `kind` field. **Nullability by kind:** on a `"price"` row the structured fields (`class`, `underlying`, `expiry`, `targetPrice`, `period`) are populated and `category` / `subCategory` are `null`; on a `"canonical"` row those structured fields are `null` and `category` / `subCategory` are populated. Request semantics — id-set merging, child expansion via `question_ids`, parent-question derivation from child outcomes, 50-id cap — are unchanged.