/api/v1/mystery/catalog/:tier_id/odds read:catalog The rarity breakdown, what’s currently available, and the value per item for one tier, ready to show players before they buy. Read `scope` first: normally it is `onchain`, the authoritative odds governed by the pool contract’s own tier weights. If the chain is briefly unreachable the endpoint answers with `scope: "inventory_fallback"` instead — availability-derived odds, a different set of fields, and NOT the published pull rates. Branch on `scope` rather than probing for fields.
Both shapes carry `tier_id`, `currency` and `rarity_groups[]`; everything else differs. Show published odds only from `scope: "onchain"` — the fallback describes what happens to be in stock right now, which is not the same number.
GET /api/v1/mystery/catalog/1/odds These inputs are shared across all docs pages, so an id entered here carries over.
{
"success": false,
"message": "Mystery partner API key required",
"error": "This endpoint requires an API key linked to a mystery partner account"
}curl -X GET 'https://service.rip.fun/api/v1/mystery/catalog/1/odds' \ -H 'X-API-Key: rip_…'
| Field | Type | Required | Description |
|---|---|---|---|
fresh | query bool | — | `true` bypasses the shared response cache and recomputes from source. Meant for a manual refresh, not for polling: it carries its own budget of 10 calls per minute per key, and past that you get a 429 while a plain read still answers from cache |
data)| Field | Description |
|---|---|
scope | `onchain` (authoritative, the normal answer) or `inventory_fallback` (the chain read failed; availability-derived). Every field below is marked with the shape it belongs to |
tier_price_usdc / target_ev_usdc / slot_count / active | onchain only — the tier as the pool contract has it: price, target EV, how many items a pull yields, and whether it is selling |
rarity_groups[].group_id / name / tier_label / color | Both shapes — display metadata per rarity group |
rarity_groups[].min_price / max_price / avg_price | Both shapes — value range within the group |
rarity_groups[].weight / probability | onchain — the group’s pull weight and its share across all slots: the expected fraction of pulled items, and the number to publish |
rarity_groups[].available_count | Both shapes — how many items of that group are in stock right now. Supplementary on the onchain shape; on the fallback it IS the probability’s denominator |
slots[] | onchain — the per-slot breakdown: `{ slot_index, slot_type, min_value_usdc, max_value_usdc, groups[] }`, each group with its `group_id`, `weight` and within-slot `probability` |
total_available / average_item_value | inventory_fallback only — items in the pool and the inventory-derived EV per item (USDC decimal string) |
| Status | Code | When |
|---|---|---|
| 400 | invalid_tier | tier_id is not a known tier |
See Errors for the response envelope and the full code list.