HIP-4 Prediction Market Types: Binary, Multi, Bucket

In HIP-4, a prediction market is a probability instrument priced between 0 and 1, where the price reflects the market’s implied probability that a given outcome will occur. Each market has two tradeable sides - for example, “Yes” and “No” - and each side is a separate token. If you buy “Yes” at 0.65, you’re paying 0.65 USDH per share and receiving a payout of 1 USDH per share if the outcome resolves in your favor. The SDK classifies every live outcome into one of four typed market structures, each carrying pre-computed side identifiers and metadata that makes it straightforward to display, filter, and trade.

Market types

HIP-4 markets fall into four types, each with its own structure and set of fields.

defaultBinary
labelledBinary
priceBucket

(aka priceBinary)Recurring price binary markets are auto-generated on a schedule and ask whether an asset’s price will exceed a target by a given expiry. They always use “Yes” / “No” sides.

e.g. “Will BTC finish above $82,000 at 23:59 11/05/2026”

Distinguishing fields: underlying, targetPrice, expiry, period

import type { DefaultBinaryMarket } from "@outcome.xyz/hip4";

const market = markets[0] as DefaultBinaryMarket;

market.type;           // "defaultBinary"
market.underlying;     // "BTC"
market.targetPrice;    // 69070
market.expiry;         // Date (UTC)
market.period;         // "1d"
market.sides[0].name;  // "Yes"
market.sides[0].coin;  // "#17580"
market.sides[0].asset; // 100017580
market.sides[1].name;  // "No"
market.sides[1].coin;  // "#17581"

Fetch recurring markets specifically:

const recurring = await hip4.events.fetchMarkets({ type: "defaultBinary" });

Standalone binary markets with custom side names. These are one-off markets not grouped under a parent question. The sides can be anything - “True” vs “False”, “Hypurr” vs “Usain Bolt”, “Pass” vs “Fail” - as defined by the market creator.

e.g. “Hyperliquid is the best DeFi ecosystem (true / false)”

Distinguishing fields: custom sides[n].name values (not “Yes”/“No”)

import type { LabelledBinaryMarket } from "@outcome.xyz/hip4";

const market = markets[0] as LabelledBinaryMarket;

market.type;           // "labelledBinary"
market.sides[0].name;  // e.g. "Hypurr"
market.sides[1].name;  // e.g. "Usain Bolt"
market.sides[0].coin;  // "#900"

Multi-bucket price range markets. Instead of a single binary threshold, the parent question defines N price thresholds that create N+1 buckets. Each bucket is its own priceBucket market, representing whether the price will land in that range at expiry.

e.g. “Where will the BTC price be at 23:59 11/05/2026” with option ”< $80,000”, “$80,000-$82,000” or ”>$82,000”

Distinguishing fields: priceThresholds, lowerBound, upperBound, bucketIndex, isFallbackThe class:priceBucket tag appears on the parent question’s description, not the individual outcome. N thresholds produce N+1 bucket outcomes plus one settlement fallback outcome.

import type { PriceBucketMarket } from "@outcome.xyz/hip4";

const market = markets[0] as PriceBucketMarket;

market.type;             // "priceBucket"
market.underlying;       // "BTC"
market.expiry;           // Date (UTC)
market.period;           // "15m"
market.priceThresholds;  // [81015.3, 81258.7]
market.lowerBound;       // 81015.3  (null = unbounded below)
market.upperBound;       // 81258.7  (null = unbounded above)
market.bucketIndex;      // 1  (-1 for the fallback outcome)
market.isFallback;       // false

Market type summary

Type	Description	Key fields
`defaultBinary`	Recurring price binary (auto-generated)	`underlying`, `targetPrice`, `expiry`, `period`
`labelledBinary`	Standalone binary with custom side names	Custom `sides[n].name` values
`priceBucket`	Grouped under a parent question	`questionId`, `questionName`, `isFallback`

Data hierarchy

HIP-4 structures data in three layers: events, markets, and outcomes.

PredictionEvent  (e.g. "Will BTC hit $69k?")
└── PredictionMarket  (the tradeable question, id = outcome ID as string)
    ├── PredictionOutcome  (side 0 - "Yes")
    └── PredictionOutcome  (side 1 - "No")

A PredictionEvent groups one or more PredictionMarket objects. For question-based events (multi-outcome), each named outcome becomes its own PredictionMarket. For standalone outcomes, the event contains a single market. PredictionOutcome represents one side. It carries the side name, the tokenId (the side coin like #5160), and the current price as a decimal string between “0” and “1”.

import type { PredictionEvent, PredictionMarket, PredictionOutcome } from "@outcome.xyz/hip4"

const event: PredictionEvent = await hip4.events.fetchEvent("q1");

event.id;          // "q1"
event.title;       // "Which team wins the championship?"
event.status;      // "active"
event.markets;     // PredictionMarket[]

const market: PredictionMarket = event.markets[0];
market.id;         // "516"  (outcome ID as string)
market.question;   // "Team A"
market.outcomes;   // PredictionOutcome[]

const outcome: PredictionOutcome = market.outcomes[0];
outcome.name;      // "Yes"
outcome.tokenId;   // "#5160"
outcome.price;     // "0.65"

Event IDs

Event IDs follow two formats depending on how the market was created:

q{n} - a question-based event grouping multiple named outcomes (e.g. "q42")
o{n} - a standalone outcome that forms its own single-market event (e.g. "o516")

Recurring markets and labelled binary markets are typically standalone and use the o{n} format. Price bucket markets are always question-based and use q{n}.

const questionEvent = await hip4.events.fetchEvent("q42");   // multi-outcome
const standaloneEvent = await hip4.events.fetchEvent("o516"); // binary

Market status

Every PredictionEvent has a status field that reflects its current lifecycle state.

Status	Meaning
`"active"`	Trading is open
`"pending_resolution"`	Market has closed; awaiting settlement
`"resolved"`	Outcome has been determined
`"cancelled"`	Market was voided

const events = await hip4.events.fetchEvents({ active: true });
// Returns only events with status "active"

const event = await hip4.events.fetchEvent("q1");
if (event.status === "resolved") {
  // Show resolution result
}

​Market types

​Market type summary

​Data hierarchy

​Event IDs

​Market status

Market types

Market type summary

Data hierarchy

Event IDs

Market status