> 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 Get registered prediction market outcomes by their outcome IDs or asset IDs. 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 | | `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 | 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 | 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.