Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

settledOutcomesById

Get settled prediction market outcomes by their outcome IDs or asset IDs.

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

POST Request

Field
Type
Description

type

string

Must be "settledOutcomesById"

kind

string

"all" (default for by-id), "price", or "canonical" — see The kind filter (optional)

outcome_ids

integer[]

Array of outcome IDs (optional)

asset_ids

string[]

Array of asset IDs prefixed with #, e.g. "#90" (optional)

question_ids

integer[]

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.

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"]
  }'
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())

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.

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

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. null when kind is "canonical"

targetPrice

string?

Numeric strike for priceBinary; bucket-range string for priceBucket (see Target price formats above). null when kind is "canonical"

period

string?

Period. 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}"

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

settleDetails

string?

Numeric settle price for price markets (e.g. "73336"); freeform decision text for canonical markets

yesStats

object

YES-side market stats; zero-valued when no fills (see Stats object below)

noStats

object

NO-side market stats

deployerAddress

string?

Permissionless-venue deployer address; null on validator-registered outcomes

deployerVenue

string?

Permissionless venue name; null on validator-registered outcomes

templateId

string?

Template the outcome was deployed from, e.g. "binaryPrice" (see outcomeTemplatesOverview); null on outcomes not created from a template

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

outcomeIds 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

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

deployerAddress

string?

Permissionless-venue deployer address; null on validator-registered questions

deployerVenue

string?

Permissionless venue name; null on validator-registered questions

templateId

string?

Template the question was deployed from, e.g. "sportsContestResult" (see outcomeTemplatesOverview); null on questions not created from a template

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

Response

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.

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.

PrevioussettledOutcome
NextsettledOutcomes

Last updated