> For the complete documentation index, see [llms.txt](https://mute-sh.gitbook.io/mute.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mute-sh.gitbook.io/mute.sh/api/api-reference/outcomes.md). # Outcomes Where markets are coin-centric (raw trading units), **outcomes are market-centric**: one `outcome_id` = one question with two sides. This family is the enriched taxonomy surface — AI-classified categories, human titles, settlement state, and per-side stats — and it comes in three lifecycle views: | Family | Question it answers | Envelope | | ------------------------ | ------------------------------------------------------ | -------------------------------------------- | | `/v1/outcomes` | "what's tradable, what is it about, how's it doing?" | `{ count, offset, outcomes: [] }` | | `/v1/registeredOutcomes` | "what just got listed?" (newest first by registration) | `{ count, offset, registered_outcomes: [] }` | | `/v1/settledOutcomes` | "what resolved, who won, what was paid?" | `{ count, offset, settled_outcomes: [] }` | ## The outcome ↔ coin formula Every outcome's two tradable coins are derived arithmetically: ``` coin = "#" + (outcome_id × 10 + side_idx) side_idx ∈ {0, 1} ``` Outcome `736` → coins `#7360` (side 0 = `side_a`) and `#7361` (side 1 = `side_b`). Reverse: `outcome_id = floor(N / 10)`, `side_idx = N % 10`. This is the bridge between this family and everything coin-keyed (`/v1/fills`, `/v1/markets/*`, the activity stream's `outcome_id`/`side_idx` fields). ## Shared meta fields All three families derive their metadata identically (same server-side join), so these fields mean the same thing everywhere: | Field | Meaning | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | best display name: AI-cleaned title when available, else the question name, else raw `name` | | `name` / `description` | raw on-chain values — `description` is resolution-criteria prose for `named` markets, a `class:…\|underlying:…\|targetPrice:…` spec string for price markets, `index:N` for bucket legs | | `category` / `subcategory` | classification with AI fallback. Live taxonomy today: `crypto/{btc,eth,sol,hype}`, `sports/{football,basketball}`, `macro/{cpi,fed}`, `other` | | `tags` / `ai_confidence` | AI enrichment extras (`tags` is currently `[]` on most rows) | | `market_class` | `named`, `priceBinary`, `priceBucket` — plus `fallback` (the catch-all "none of the named outcomes" leg of a question group) | | `side_a_name` / `side_b_name` | labels for side 0 / side 1 (`Yes`/`No`, or team names) | | `expiry` | UTC datetime; **`1970-01-01 00:00:00.000` is the "no scheduled expiry" sentinel** (event markets resolve when the event ends) | | `target_price` | **string** here (e.g. `"63927"`), unlike the numeric field in `/v1/markets` responses | | `settlement_px` | **`-1` = not settled** (sentinel); once resolved: `1`/`0` for binaries (side A won/lost), or a price level for buckets | | `first_seen` | when the indexer first saw the outcome — the "registered at" timestamp | *** ## GET /v1/outcomes The enriched list, sorted hottest-first (`volume_24h`, then lifetime volume). Defaults to **active markets only**. | Query param | Type | Default | Description | | -------------- | ------ | -------- | -------------------------------- | | `status` | enum | `active` | `active` \| `settled` \| `all` | | `category` | string | — | e.g. `sports`, `crypto`, `macro` | | `underlying` | string | — | e.g. `BTC` | | `market_class` | string | — | e.g. `priceBinary` | | `limit` | int | `50` | 1–200 | | `offset` | int | `0` | pagination | ```bash curl -H "X-API-Key: $MUTE_KEY" "https://api.mute.sh/v1/outcomes?limit=2" ``` ```json { "count": 2, "offset": 0, "outcomes": [ { "outcome_id": 740, "title": "World Cup Round of 16: Paraguay vs France", "name": "World Cup Round of 16: Paraguay vs France", "question_name": "", "market_class": "named", "underlying": "", "category": "sports", "subcategory": "football", "tags": [], "is_settled": false, "side_a_name": "Paraguay", "side_b_name": "France", "expiry": "1970-01-01 00:00:00.000", "period": "", "target_price": "0", "settlement_px": -1, "volume_usd": 1575741.49, "volume_24h": 1536288.32, "trades": 6232, "traders": 511, "last_trade_at": "2026-07-05 06:07:59.111" } ] } ``` The stats columns (`volume_usd`, `volume_24h`, `trades`, `traders`) **exclude settlement legs** — they measure real trading, and they aggregate **both sides** of the outcome. *** ## GET /v1/outcomes/categories The facet index: every `category`/`subcategory` pair with outcome counts — build filter UIs from this instead of hardcoding the taxonomy. ```bash curl -H "X-API-Key: $MUTE_KEY" "https://api.mute.sh/v1/outcomes/categories" ``` ```json { "categories": [ { "category": "crypto", "subcategory": "btc", "outcomes": 302, "settled": 292 }, { "category": "sports", "subcategory": "football", "outcomes": 289, "settled": 230 }, { "category": "other", "subcategory": "", "outcomes": 81, "settled": 0 }, { "category": "macro", "subcategory": "cpi", "outcomes": 4, "settled": 4 } ] } ``` `outcomes - settled` = live market count per facet. *** ## GET /v1/outcomes/:id The full dossier for one outcome — meta, live per-side prices, question context, settlement history, and recent trades in a single call. ```bash curl -H "X-API-Key: $MUTE_KEY" "https://api.mute.sh/v1/outcomes/154" ``` ```json { "outcome_id": 154, "title": "Recurring", "description": "class:priceBinary|underlying:BTC|expiry:20260605-0600|targetPrice:63927|period:1d", "market_class": "priceBinary", "underlying": "BTC", "category": "crypto", "subcategory": "btc", "is_settled": true, "side_a_name": "Yes", "side_b_name": "No", "target_price": "63927", "settlement_px": 0, "first_seen": "2026-06-04 06:00:19.000", "sides": [ { "coin": "#1540", "side_idx": 0, "name": "Yes", "last_px": 0.678, "implied_probability": 0.678, "last_trade_at": "2026-06-05 06:00:04.501", "volume_usd": 3495337.6, "volume_24h": 0, "trades": 69569, "traders": 300 }, { "coin": "#1541", "side_idx": 1, "name": "No", "last_px": 0.322, "implied_probability": 0.322, "last_trade_at": "2026-06-05 05:58:41.220", "volume_usd": 812445.1, "volume_24h": 0, "trades": 15204, "traders": 188 } ], "question": null, "settlement_events": [ { "time": "2026-06-05 06:00:06.000", "event_type": "settlement", "signer": "", "settle_fraction": "0", "settle_details": "price:62291.3" } ], "recent_trades": [ { "time": "…", "coin": "#1541", "side": "A", "px": 1, "sz": 18, "dir": "Settlement" } ] } ``` * `sides[]` is the per-coin live view: `last_px` (= `implied_probability`) is the latest non-settlement trade price — **this is where you read current market odds**. It **always contains both sides** — a side that has never traded appears with `last_px: null` and zeroed stats rather than being omitted. `name` is the human side label (`side_a_name`/`side_b_name` — team names for knockout fixtures, `Yes`/`No` otherwise). * `question` is non-null when the outcome belongs to a multi-outcome question group (e.g. a "who wins the World Cup" ladder): it carries `named_outcomes[]`, the `fallback_outcome`, and which named outcomes already settled. * `settlement_events` includes creations and (once resolved) the settlement with its input (`price:62291.3`). * `recent_trades` is the last 20 fills across both sides. **Errors:** unknown or non-numeric id → `404` (`"Outcome 99999999 not found"` / `"Invalid outcome id"`). *** ## GET /v1/registeredOutcomes The listing feed: outcomes ordered by **`first_seen` DESC** — "what just went live". Same row shape as `/v1/outcomes` plus `first_seen` and `first_trade_at`, minus the 24 h column. Fresh listings show `volume_usd: 0` and empty trade timestamps — early-traction watching is the point of this endpoint. | Query param | Type | Default | Description | | ------------------------------------------ | ------ | ------- | ------------------------------ | | `underlying` / `category` / `market_class` | string | — | same filters as `/v1/outcomes` | | `limit` | int | `50` | 1–200 | | `offset` | int | `0` | pagination | ```bash curl -H "X-API-Key: $MUTE_KEY" "https://api.mute.sh/v1/registeredOutcomes?limit=2" ``` ```json { "count": 2, "offset": 0, "registered_outcomes": [ { "outcome_id": 757, "title": "Recurring Fallback", "market_class": "fallback", "category": "other", "is_settled": false, "settlement_px": -1, "first_seen": "2026-07-05 10:17:52.000", "volume_usd": 0, "trades": 0, "traders": 0, "first_trade_at": "", "last_trade_at": "" } ] } ``` **Caching:** `public, max-age=30`. ### GET /v1/registeredOutcomes/snapshot Bulk sync: **every** registered outcome, minimal columns only (`outcome_id`, `title`, `name`, `market_class`, `underlying`, `category`, `is_settled`, `expiry`, `first_seen`). Default `limit` is **5000** (the whole universe fits in one call today). Use this to build a local index, then hydrate details on demand. **Caching:** `public, max-age=3600` — designed for periodic sync, not polling. ### GET /v1/registeredOutcomes/:id One outcome's full meta (flat object, no stats join). `404` if unknown — and note **404s are cached for an hour too** (same `Cache-Control` as hits), so don't poll this endpoint waiting for a brand-new id to appear; use the list endpoint's 30 s view instead. *** ## GET /v1/settledOutcomes The resolution ledger: every settled outcome joined with its settlement legs — who held, who won, what was paid. All metrics here are **settlement-scoped** (the opposite convention from `/v1/outcomes`, which excludes settlement legs). | Query param | Type | Default | Description | | ------------------------------------------ | ------ | ------- | ------------------------------ | | `underlying` / `category` / `market_class` | string | — | same filters as `/v1/outcomes` | | `limit` | int | `50` | 1–200 | | `offset` | int | `0` | pagination | ```bash curl -H "X-API-Key: $MUTE_KEY" "https://api.mute.sh/v1/settledOutcomes?limit=1" ``` ```json { "count": 1, "offset": 0, "settled_outcomes": [ { "outcome_id": 736, "title": "Recurring Named Outcome", "market_class": "priceBucket", "underlying": "BTC", "category": "crypto", "settlement_px": 0, "settled_at": "2026-07-04 06:00:18.147", "holders_settled": 23, "winners": 22, "losers": 32, "total_payout": 24976, "settled_shares": 50476, "settled_pnl": -676.23, "winning_coin": "#7361", "winning_side_idx": 1 } ] } ``` | Field | Meaning | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `winning_coin` / `winning_side_idx` | the coin that settled at `px = 1` and which side it was | | `holders_settled` / `winners` / `losers` | wallets holding at resolution, split by side held | | `total_payout` | USD paid to winners (`Σ px·sz` over settlement fills — losers contribute 0) | | `settled_shares` | shares swept across both sides | | `settled_pnl` | net realized USD PnL across all holders at settlement — negative when the crowd (or an MM) ate a loss | ### GET /v1/settledOutcomes/:id Per-side breakdown of one resolution: meta + `winning_coin` + `settlement_totals` + a `sides[]` array (one entry per coin with `result: "won"|"lost"`, holders, shares, payout, PnL) + the raw `settlement_events`. ```json { "outcome_id": 736, "winning_coin": "#7361", "winning_side_idx": 1, "settlement_totals": { "holders_settled": 29, "winners": 12, "losers": 17, "total_payout": 24976, "settled_shares": 50476, "settled_pnl": -676.23 }, "sides": [ { "coin": "#7360", "side_idx": 0, "settlement_px": 0, "result": "lost", "holders": 17, "settled_shares": 25500, "payout": 0, "settled_pnl": -2862.27, "settled_at": "2026-07-04 06:00:18.147" }, { "coin": "#7361", "side_idx": 1, "settlement_px": 1, "result": "won", "holders": 12, "settled_shares": 24976, "payout": 24976, "settled_pnl": 2186.04, "settled_at": "2026-07-04 06:00:18.147" } ], "settlement_events": [ { "time": "2026-07-04 06:00:18.000", "event_type": "settlement", "settle_fraction": "0", "settle_details": "price:62463.5" } ] } ``` **Two distinct 404s:** `"Outcome X not found"` (unknown id) vs `"Outcome X has not settled yet"` (known, still live) — the second flips to a `200` the moment the market resolves, which for live sports can be seconds after the final whistle. ### GET /v1/settledOutcomes/address/:address A wallet's settlement record — the outcomes it **held through resolution**. This is *not* "everything the wallet traded": a position fully closed before settlement has no settlement leg and doesn't appear. | Query param | Type | Default | Description | | ----------- | ---- | ------- | ------------------------ | | `result` | enum | `all` | `won` \| `lost` \| `all` | | `limit` | int | `100` | 1–200 | | `offset` | int | `0` | pagination | ```bash curl -H "X-API-Key: $MUTE_KEY" \ "https://api.mute.sh/v1/settledOutcomes/address/0xaddc680878f96b93189f700d17f4a9bfcf80ff54?limit=1" ``` ```json { "user": "0xaddc680878f96b93189f700d17f4a9bfcf80ff54", "result": "all", "count": 1, "offset": 0, "summary": { "positions_settled": 128, "wins": 70, "losses": 58, "total_payout": 1211291, "total_settled_pnl": 258903.4 }, "settled_positions": [ { "outcome_id": 744, "coin": "#7441", "side_idx": 1, "side": "A", "settlement_px": 1, "result": "won", "settled_shares": 1000, "payout": 1000, "settled_pnl": 125.27, "settled_at": "2026-07-05 06:00:29.823", "title": "Recurring", "market_class": "priceBinary", "underlying": "SOL", "category": "crypto", "expiry": "2026-07-05 06:00:00.000", "period": "1d" } ] } ``` Two things to get right as an integrator: * **`summary` is always the wallet's lifetime totals** — the `result` filter narrows `settled_positions[]` only. `count` counts the filtered page, not the lifetime record. * **A famous trader can legitimately return zero rows.** Wallets that trade in and out before expiry (market makers, scalpers) never hold through settlement — the top-PnL trader on the leaderboard had `settlements: 0` here. Absence means "didn't hold to resolution", not "didn't trade". Malformed address → `400 Invalid address`. *** ## Choosing the right list * Rendering a market browser → `/v1/outcomes` (hot-first, live stats, category facets from `/outcomes/categories`) * Syncing your own database / search index → `/registeredOutcomes/snapshot` hourly + `/registeredOutcomes?limit=…` every 30 s for the delta * New-listing alerts → poll `/registeredOutcomes` (30 s cache) and diff on `outcome_id` * Results/history pages, win-rate stats, "did I win?" → `/settledOutcomes` family * Live odds for one market → `/v1/outcomes/:id` → `sides[].implied_probability` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://mute-sh.gitbook.io/mute.sh/api/api-reference/outcomes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.