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	Anywhere marketId is accepted

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 has the same property — the outcomeId format for 1m candles is venue-specific, and Historical data documents the shape per venue.

The rule: REST reads take Predictefy ids; anything that touches a venue’s live feed takes that venue’s ids. Mixing them is the failure that produces an empty subscription rather than an error, because the venue simply has nothing under the id you sent.

Slugs

A slug is a readable alias accepted anywhere marketId is. It is convenient in URLs and in hand-written queries.

Prefer marketId for anything stored. Slugs are derived from titles, and a venue that renames a market can change its slug — an id you persisted six months ago may no longer resolve, 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.