> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Identifiers

> Which id each verb expects, where venue-native ids surface, and why the wrong one fails quietly.

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:

```sh
# 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](/guides/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](/guides/history/) 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 `marketId`s, and neither is convertible into the other.

Relating them is what [matched clusters](/guides/cross-venue/) 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.