- btc-updown-5mSlug
- 0x conditionIdId
- UP ·
DOWNTokens - by-slugLookup
Slugs are how humans name markets; conditionIds are how the API addresses them. A slug like btc-updown-5m is readable and stable to type, but every snapshot, orderbook and summary endpoint keys off the 0x conditionId underneath it. Resolving one to the other is a one-call step, and skipping it is the most common reason a first query 404s.
Two identifiers describe the same market. The slug, btc-updown-5m, eth-updown-1h, is the friendly alias you can read and guess. The conditionId is a 0x hash: unambiguous, machine-stable, and the value the data endpoints actually expect in their :id slot.
Why the conditionId is the real handle
A slug is convenient but coarse. Crypto markets roll over constantly, a fresh btc-updown-5m opens every five minutes, so the slug alone does not pin down which instance you mean. The conditionId does: it names one specific market, for its whole life, even after it closes and settles. That is why /v1/markets/:id/orderbook, /v1/markets/:id/snapshots and /v1/markets/:id/summary all want the conditionId, not the slug.
One call turns a slug into an id
Send a slug to /v1/markets/by-slug/:slug and you get the resolved market back, its 0x conditionId, the coin and timeframe, and the two token ids. From an AI assistant, the MCP get_market tool does the same resolution. Either way it is one step, and you only do it once per market.
The UP / DOWN token structure
A market is not one order book, it is two. Each crypto market resolves to a pair of tokens, UP and DOWN, and each token has its own independent order book. UP pays out if the underlying finishes above the strike; DOWN pays out if it finishes below. Their prices are complementary probabilities: when the UP token trades around 0.62, the DOWN side trades around 0.38, and the winner settles at 1 while the loser settles at 0.
Two complementary books
UP and DOWN each carry a full bid/ask ladder. They are linked by the 1.00 sum, but quoted and filled independently.
- Independent depth
- Prices sum to ~1
- Pick a side per query
One conditionId, both tokens
The conditionId addresses the market; the side parameter selects which token’s book you read within it.
- Id names the market
- side names the token
- Resolve once, reuse
Stable across the lifecycle
Closed markets keep their conditionId and stay queryable, so a resolved id keeps working long after settlement.
- Persists post-close
- No survivorship gap
- Reproducible references
A practical lookup, end to end
- 1Start with what you can read, a slug like btc-updown-1h, or a market you spotted in /v1/markets/live.
- 2Resolve it: call /v1/markets/by-slug/:slug (or MCP get_market) and read the 0x conditionId off the response.
- 3Carry the conditionId into the data calls, orderbook, snapshots or summary, and use the side parameter to choose UP or DOWN.
- 4Cache the mapping. A market’s slug-to-id pairing is fixed for that market’s life, so resolve once and reuse rather than looking it up on every request.
- by-slug /
:slugResolve a slug to its market record - 0x conditionIdThe id every data endpoint expects
- UP ·
DOWNTwo token books per market get_marketThe MCP equivalent for AI assistants
- Do not pass a slug where an endpoint wants :id, the snapshot, orderbook and summary routes resolve on the conditionId, and a slug there will simply not match.
- Because new crypto markets open every few minutes, resolve fresh when you target “the current 5m” rather than reusing yesterday’s id.
- For a closed market you studied last month, the same conditionId still resolves, settled markets stay in the archive.
- When you only know the coin and timeframe, /v1/markets/live is the fastest way to a current, real conditionId.
Slugs are for people; conditionIds are for queries. Resolve once, cache the pair, and every downstream call has the one handle it actually needs.
Resolve your first market
The docs cover the by-slug route and the id-keyed endpoints; the crypto page lists the coins and timeframes you can resolve.
Frequently asked questions
What is the difference between a slug and a conditionId?
A slug like btc-updown-5m is a human-readable alias; the conditionId is the 0x hash that uniquely names one market for its whole life. The data endpoints, orderbook, snapshots, summary, all key off the conditionId, so the slug is just the readable handle you resolve from.
How do I resolve a slug to a conditionId?
Call /v1/markets/by-slug/:slug with the slug, or use the MCP get_market tool from an AI assistant. Either returns the market record including its 0x conditionId plus the UP and DOWN token ids. It is a one-call step, and the mapping is stable, so you can cache it.
Why does each market have two tokens?
Each crypto market is a pair: an UP token that settles to 1 if the underlying finishes above the strike, and a DOWN token that settles to 1 if it finishes below. Each token has its own order book, and their prices are complementary probabilities that sum to roughly one.
Does the conditionId still work after a market closes?
Yes. Closed and settled markets keep their conditionId and stay queryable in the archive, so a resolved id keeps returning history long after the market ends. That persistence is what lets you reference and reproduce a study on a market that has already resolved.