Markets, outcomes & matching

The data modelCopy Anchor Link

Every venue lists its own copy of a real-world question. sufwan-local-test stores each venue's listing and links equivalent ones together into a matched cluster.

You trade an outcome. Quotes, direct orders, and limit orders all take a venueMarketOutcomeId. Orderbook and midpoint reads take the market id or the outcome id, depending on the route. The two are not interchangeable.

Each object also carries externalIdentifier, the venue's own id (a Kalshi ticker, a Polymarket token id).

Market status is one of unopened, paused, open, closed, or resolved. Only open markets can be traded. How a closed or resolved market pays out, including splits and voids, is covered in Market resolution & voids.

Find a market to tradeCopy Anchor Link

import { MarketStatus } from "@agg-build/sdk";

const markets = await client.getVenueMarkets({ status: MarketStatus.open, search: "bitcoin", limit: 5 });
const outcomeId = markets.data[0]?.venueMarketOutcomes?.[0]?.id;

Each market in data[] carries venueMarketOutcomes[]. Take the outcome's id. Prices are not on the listing; read them from GET /midpoints or a quote. For full filters and search modes see Building market views and the List venue markets reference.

24-hour price changeCopy Anchor Link

Each outcome carries priceChange24h: how far its price moved over the last 24 hours, in absolute probability points. 0.05 means the outcome is up 5 cents; -0.12 means down 12 cents. It is not a percentage.

• null means unknown, never zero. Some venues publish no 24-hour change, so we sample their prices ourselves; their markets read null for roughly their first 24 hours.
• The value is refreshed out of band, so it can trail the live price. Use GET /midpoints for the live price itself. How often it refreshes depends on the venue:
  • Polymarket: about every 5 minutes for the 5,000 most traded markets, and every few minutes for other active markets. Quiet markets can take hours.
  • Myriad: every few minutes.
  • Kalshi and Hyperliquid: about every 30 minutes.
  • Venues we sample ourselves: about every 15 minutes.
• /search results do not include it; read it from /venue-markets, /venue-events or /venue-market-outcomes.

Across venuesCopy Anchor Link

See Identifiers for cross-venue joins and durable references. To turn a venue's own id into an outcome, call GET /venue-market-outcomes (Look up venue market outcomes by external identifier).

Settlement can differCopy Anchor Link

Venues do not always settle the same question the same way, for example on timing or on a cancelled match. GET /venue-events/:id returns a per-venue breakdown of those differences. Show it before users trade across venues.

Discover markets by topicCopy Anchor Link

Use these guides when building a focused discovery experience:

• Live crypto markets: browse recurring price windows and add the underlying asset's reference price.
• News feeds: connect articles to the markets they discuss.
• Correlated markets: find markets connected by related outcome signals, beyond title matching.

GuidesCopy Anchor Link