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

settledOutcomes

Get recent settled prediction market outcomes.

Returns a list of recently settled prediction market outcomes, ordered by most recent first.

POST Request

Field
Type
Description

type

string

Must be "settledOutcomes"

limit

integer

Max results to return, default 100, max 100 (optional)

cursor

string

Take the cursor from the previous response to fetch the next page. Omit (or send null) for the first page. Must be a string — a number is a 400 — see Pagination (optional)

kind

string

"all" (default), "price", or "canonical" — see The kind filter (optional)

name

string

Filter by outcome name (optional)

class

string

Filter by outcome class, e.g. "priceBinary" (optional)

underlying

string

Filter by underlying asset, e.g. "HYPE" (optional)

period

string

Filter by period, e.g. "15m" (optional)

category

string

Filter by canonical-market category, e.g. "sports", case-insensitive (optional)

subCategory

string

Filter by canonical-market sub-category, case-insensitive (optional)

search

string

Free-text search across name, description, category and subCategory — see Free-text search (optional)

venue

string

Only outcomes deployed by this permissionless venue, e.g. "skew". 2–4 ASCII letters, case-insensitive (optional)

deployedBy

string

"all" (default), "validator" (registered by validator quorum, no venue), or "venue" (any permissionless venue) (optional)

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.

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "settledOutcomes",
    "limit": 10,
    "underlying": "HYPE"
  }'
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'settledOutcomes',
        'limit': 10,
        'underlying': 'HYPE'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

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

Response Fields

Returns an object with two arrays — outcomes (the settled 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) — plus the two pagination fields below. Both arrays are always present, even when empty.

Field
Type
Description

outcomes

array

The settled outcome objects on this page

questions

array

Parent questions of the outcomes on this page

hasMore

boolean

true when another page follows

cursor

string

Pass to the next request to continue. Absent on the last page

The limit, cursor 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. hasMore and cursor likewise describe outcomes only; questions is not paginated. 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).

Pagination

Walk the full result set by holding limit and the filters fixed and passing back the cursor from each response until it is absent:

Send the cursor back exactly as you received it, as a string. A numeric cursor returns a 400.

The cursor is exclusive, so no outcome appears on two pages. The list is live, though: a market that settles mid-walk shows up at its own outcomeId. If that sits above your cursor you have already walked past it, and it will not appear.

Keep the filters identical across a walk. Changing one invalidates the cursor.

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

targetPrice

string?

Numeric strike for priceBinary; bucket-range string for priceBucket (see 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, e.g. "sports". 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?

Settlement result: numeric settle price as a string for price markets (e.g. "73336"); freeform decision text for canonical markets

yesStats

object

YES-side market stats. Always present; 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

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

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). null until the question settles

winningNamedIndex

integer?

Position in namedOutcomes of the winner if a named child won, null if the fallback won (or unsettled)

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

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.

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

The example covers three settled outcomes — a named priceBucket child (7604), the fallback child of the same question (7601), and a standalone priceBinary outcome (7600) — all with settleFraction: "0" ("0" for losers, "1" for the winner). Question 302's actual winner is 7603, surfaced in the question's winningOutcome field; the question itself is automatically derived into questions because its child 7604 appears in outcomes.

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 (priceBinary / priceBucket).

"canonical"

HIP-4 validator-voted (prose) markets only.

The response shape is identical regardless of kind — the same outcomes / questions envelope, sort order, stats objects, and limit semantics. 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.

PrevioussettledOutcomesById
NextregisteredOutcomesById

Last updated