How to fetch and filter HIP-4 prediction markets

The events adapter gives you structured access to every HIP-4 prediction market on Hyperliquid. Markets are returned as typed objects with pre-computed coin identifiers so you can go straight from discovery to trading without any manual ID mapping.

Fetch all markets

hip4.events.fetchMarkets() returns a flat HIP4Market[] array covering every outcome in Hyperliquid’s outcomeMeta catalog.

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

const hip4 = createHIP4Adapter({ testnet: true });
await hip4.initialize();

const markets = (await hip4.events.fetchMarkets()) as HIP4Market[];
console.log(`${markets.length} markets available`);

Filter by type

Pass a type filter to narrow results to a specific market category.

// Recurring price binary markets (BTC > $69,000 in 1h, etc.)
const recurring = await hip4.events.fetchMarkets({ type: "defaultBinary" });

// Standalone binary markets with custom side names
const labelled = await hip4.events.fetchMarkets({ type: "labelledBinary" });

// Multi-outcome markets grouped under a parent question
const multi = await hip4.events.fetchMarkets({ type: "multiOutcome" });

// Multi-bucket price range markets
const buckets = await hip4.events.fetchMarkets({ type: "priceBucket" });

Group by type

Use groupBy: "type" to receive a MarketsByType object with one key per market category.

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

const grouped = (await hip4.events.fetchMarkets({
  groupBy: "type",
})) as MarketsByType;

const defaultBinaryMarkets = (grouped.defaultBinary ??
  []) as DefaultBinaryMarket[];
const multiOutcomeMarkets = (grouped.multiOutcome ??
  []) as MultiOutcomeMarket[];

Group multi-outcome markets by question

Multi-outcome markets share a parent question. Grouping by question returns a MarketsByQuestion object keyed by question ID (or "standalone" for outcomes that don’t belong to a multi-outcome question).

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

const byQuestion = (await hip4.events.fetchMarkets({
  type: "multiOutcome",
  groupBy: "question",
})) as Record<string, MultiOutcomeMarket[]>;

for (const [questionId, options] of Object.entries(byQuestion)) {
  if (questionId === "standalone") continue;

  const first = options[0];
  console.log(`Question #${questionId}: ${first.questionName}`);

  for (const option of options) {
    const tag = option.isFallback ? " (fallback)" : "";
    console.log(`  [${option.outcomeId}] ${option.name}${tag}`);
    console.log(
      `    Yes: ${option.sides[0].coin} | No: ${option.sides[1].coin}`,
    );
  }
}

Paginate results

Use limit and offset to page through large result sets. Without limit, you get every matching market.

// Second page of 10
const page2 = await hip4.events.fetchMarkets({ limit: 10, offset: 10 });

limit and offset apply only to the flat list. When you pass groupBy, the result contains every matching market.

Sort results

Control the order of returned markets with sortBy. When you omit it, markets stay in Hyperliquid’s catalog order (the order of outcomeMeta).

// Highest 24h volume first (costs one extra request)
const byVolume = await hip4.events.fetchMarkets({ sortBy: "volume" });

// Soonest event time first; markets without one come last
const byExpiry = await hip4.events.fetchMarkets({ sortBy: "expiry" });

// Highest outcome ID (most recently created) first
const byNewest = await hip4.events.fetchMarkets({ sortBy: "newest" });

sortBy takes effect from SDK 1.3.0-beta.0. Earlier versions accept the parameter but ignore it.

Template market names

Many markets are created from Hyperliquid’s template registry (outcomeTemplates). Their name, sides[].name, and questionName are the names Hyperliquid sends, such as "template:priceTouch". From SDK 1.3.0, parsedName, sides[].parsedName, and parsedQuestionName carry the names rendered from the registry. Use them for display.

const market = markets.find((m) => m.name === "template:priceTouch")!;

market.name;                // "template:priceTouch"
market.parsedName;          // "BTC touches 90000 by Nov 1, 00:00 UTC"
market.sides[0].parsedName; // "Yes"

A template question’s fallback outcome has the parsedName "Other". Other markets repeat their name. If the registry can’t be fetched, the parsed names keep the wire names, except that the template: prefix is removed from plain names such as "template:Yes". The original outcome is always available on market.raw. Events, prices, and positions carry the same names: parsedTitle, parsedQuestion, and outcomes[].parsedName from fetchEvents and fetchEvent, outcomes[].parsedName from fetchPrice, and parsedEventTitle, parsedMarketQuestion, and parsedOutcomeName from fetchPositions. Refreshing the market or event cache makes one extra outcomeTemplates request, cached for 30 seconds.

Access typed fields on DefaultBinaryMarket

Each market type exposes fields specific to its category. DefaultBinaryMarket includes the parsed description fields you need for display and filtering.

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

const markets = (await hip4.events.fetchMarkets({
  type: "defaultBinary",
})) as DefaultBinaryMarket[];
const m = markets[0];

m.underlying; // "BTC"
m.targetPrice; // 69070
m.expiry; // Date (UTC)
m.period; // "1d"

m.sides[0].name; // "Yes"
m.sides[0].coin; // "#5160"  - use this in placeOrder
m.sides[0].asset; // 100005160
m.sides[1].name; // "No"
m.sides[1].coin; // "#5161"

m.raw; // original HLOutcome for direct API access

Fetch events and categories

Markets belong to events. You can query at the event level when you need the event title, description, status, and markets list together.

// First 50 events (fetchEvents defaults to limit: 50)
const events = await hip4.events.fetchEvents();

// Active events only
const active = await hip4.events.fetchEvents({ active: true });

// Events in the "recurring" category
const recurring = await hip4.events.fetchEvents({ category: "recurring" });

// Case-insensitive search in titles and descriptions
const btcEvents = await hip4.events.fetchEvents({ query: "BTC" });

// Single event by ID
const event = await hip4.events.fetchEvent("q42");

// Available categories
const categories = await hip4.events.fetchCategories();
// [{ id, name, slug }] - "custom" and "recurring"

Event and outcome metadata is cached for 30 seconds. Subsequent calls within that window return the cached result without hitting the network.

​Fetch all markets

​Filter by type

​Group by type

​Group multi-outcome markets by question

​Paginate results

​Sort results

​Template market names

​Access typed fields on DefaultBinaryMarket

​Fetch events and categories

Fetch all markets

Filter by type

Group by type

Group multi-outcome markets by question

Paginate results

Sort results

Template market names

Access typed fields on DefaultBinaryMarket

Fetch events and categories