Identifiers

Passing the right identifier to the right verb is the most common early integration mistake, because several of them look alike and one of them is not ours.

Id	Identifies	Used by
marketId	One question	fetchMarket, fetchRelatedMarkets, fetchHedges
outcomeId	One side of one question	fetchOrderBook, fetchOHLCV
eventId	A group of markets	fetchEvent, event filters
slug	Human-readable market alias	Selected market lookup verbs; see below

Router endpoints that resolve an anchor require canonical venue:marketId, for example polymarket:2252244; a bare venue-native id does not resolve.

Books and candles key on the outcome

fetchOrderBook and fetchOHLCV take an outcomeId, not a marketId. A binary market has one book per side, so a market id alone is ambiguous — there is no single book to return.

The normal sequence is therefore two calls, not one:

# 1. Find the market, and read its outcomes.
curl -s "$PREDICTEFY_API_URL/api/polymarket/fetchMarkets?query=fed&limit=1" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

# 2. Use an outcomeId from that response.
curl -s "$PREDICTEFY_API_URL/api/polymarket/fetchOrderBook?outcomeId=OUTCOME_ID" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Every market record carries its outcomes inline, so the second call needs no extra lookup.

Venue-native ids

Some surfaces require the venue’s own identifier rather than a Predictefy one. The clearest case is streaming: WebSocket subscriptions are made with native ids, because the subscription is proxied to the venue’s own feed.

Sub-minute history (1s, 5s, 10s, and 30s) has the same property: it requires a venue-native outcomeId. Ordinary stored-candle queries accept either canonical or venue-native outcome identity. Historical data documents coverage per venue.

The rule: follow each verb’s identifier contract. REST catalog, trader, and history surfaces accept different combinations; live-feed subscriptions use venue-native ids. Catalog-indexed subscription misses return a non-fatal MARKET_NOT_FOUND. Silent acknowledgement remains possible only on native-id lanes the validator cannot index, such as Polymarket.

Slugs

A slug is a readable alias accepted by fetchMarket, fetchRelatedMarkets, and fetchHedges. It is convenient in URLs and hand-written queries, but it is not a universal replacement for a marketId; trader surfaces, for example, do not resolve metadata.slug.

Prefer marketId for anything stored. Slugs can come from venue-provided fields or venue-specific derivation, so do not assume they are title-derived or stable. A persisted slug may stop resolving, while the marketId will.

Ids do not cross venues

There is no global identifier for a real-world question. The same event on two venues has two unrelated marketIds, and neither is convertible into the other.

Relating them is what matched clusters do, and the result is a judgement carrying a similarity score rather than an identity claim. Do not build a lookup that assumes an id from one venue means anything on another.