# Combos Request-for-Stream (RFS)

:::caution
**Status: Beta (v0.1) — dark-launched.** RFS is implemented and gated behind the `PredictionMarketsRFSEnabled` feature flag (employees-only first; the endpoints return `404` everywhere the flag is off). Message formats and field names may still change. Pages are intentionally not linked from the sidebar during the rollout.
:::

## What RFS is

RFS is a request for **liquidity on a combo contract** — a signal that says "there is demand to trade this leg set; makers, come provide a price." It separates cleanly into two steps:

1. **Contract creation (only if needed).** If the requested leg set has no contract yet, the exchange validates the legs, derives a deterministic combo ticker (the `comboSymbol`), and creates the combo contract on the spot. If the contract already exists — pre-listed by Gemini, or created by an earlier request — this step is skipped.
2. **Liquidity solicitation (always).** The request is announced on the public `requestForStream` channel. Makers see fresh demand on `comboSymbol` and post orders to its book.

Either way the output is the same: a live combo orderbook on `comboSymbol` with makers prompted to quote it. **The combo is a regular instrument** — orders, fills, depth, halts, settlement all flow through the standard combo orderbook surface. The `comboSymbol` (carrying the `CMB` ticker prefix) is the only identifier downstream tools need to recognize it as a combo.

### What it's for

RFS is fundamentally a **price-discovery** tool. A taker interested in a combo often doesn't know its fair value — especially for novel or correlated leg sets where there's no continuous market to reference — and doesn't want to commit to a price blind. Rather than guess, they submit an RFS and see what makers are willing to offer. In the same round trip, makers receive an **indication of interest**: a concrete signal that there's demand for this structure, worth pricing.

So the request serves both sides at once: the taker gets live two-sided prices to react to, and makers get a demand signal to quote against. Neither side has to know the fair value up front — it's discovered in the book that forms.

These docs cover only the RFS-specific surface: the submit endpoint, the announcement feed, the discovery filters, and how combo trading integrates with maker programs. **Everything else is standard combo orderbook**, documented in [Combo Contracts](/prediction-markets/combo-contracts/overview) and the broader [Predictions API](/rest-api/rest-api).

## Why it exists

Gemini pre-lists some combos, but the combinatorial space is far too large to enumerate in advance — `n choose k` exhausts quickly — and even a pre-listed combo often sits with no resting depth until someone wants to trade it. RFS solves both problems with one mechanism:

- **Bring novel combos into existence on demand.** A taker can request any leg set drawn from currently listed single contracts, whether or not it has ever been listed.
- **Summon liquidity to any combo that's currently quiet** — pre-listed or previously created — by signaling demand to makers.

Combos are **content-addressable**: the same leg set always produces the same `comboSymbol`. A request for a leg set that already has a contract reuses it rather than creating a duplicate, so liquidity never fragments across parallel books — the request simply re-solicits quotes on the existing one.

## Continuous discoverability and pricing

The request is **sent once** — it's not a session the taker holds open, and it imposes no duration on the responses. Everything after is continuous and maker-driven:

- **Makers** decide whether to quote, and **how long their quotes stay live** — orders rest on the combo book until the maker cancels them, like any order on the venue. No quote TTL, no refresh cycle, no obligation to keep a quote up for any minimum time.
- **Takers** can hit the book the moment a price they like appears, or come back hours later. There is no requirement to engage with the request after submitting it.
- **Discovery** is a one-event handshake (the `requestForStream` announcement); pricing is a standard orderbook process from then on.

The combo book persists until housekeeping closes it for inactivity, settlement resolves it, or a permanent leg void terminates it.

### Two perspectives on the same flow

The same protocol supports two integration styles:

- **RFQ-style UX (typical for retail-facing clients).** The user builds a combo, the client submits, the UI shows "Fetching prices..." for a few seconds while makers post to the new book, then presents the current best price(s). The user accepts or declines. Underneath, the "accept" is a standard market order against the combo's orderbook depth that built up during the window.
- **Orderbook-style integration (typical for institutional bots).** Submit, subscribe to `{comboSymbol}@depth`, manage orders against the book continuously, hit when the price meets the threshold. No UI window, no "fetching" abstraction — direct interaction with the depth feed.

Both consume the same protocol. The difference is purely in the client layer: retail-facing apps wrap the depth-watch loop in a bounded "is there a price yet?" UI; bots interact with the depth feed directly. The protocol doesn't distinguish — there is no separate "RFQ mode."

## Scope: one endpoint, every asset class

RFS accepts leg sets composed of any currently listed single contract on Gemini Predictions, across all asset classes: **crypto, sports (single-event and same-event SGP), macro, weather**, and any class added later. Cross-class leg sets — drawing from multiple classes — go through the same endpoint.

| Class | Typical leg shape | Correlation regime |
|---|---|---|
| Crypto | Strike thresholds on price at expiry | Mostly low across underlyings; structural for multi-strike on one underlying |
| Sports (cross-event) | Game outcomes, totals, player props across distinct events | Approximately independent |
| Sports (SGP / same-event) | Multiple outcomes within one game/event | High and structural; joint price ≠ product of legs |
| Macro | Print outcomes (CPI, NFP, FOMC) at scheduled release | Cross-print correlation real but tractable |
| Cross-class | Legs spanning multiple of the above | Class-pair specific |

Pricing models and halt classes vary by underlying — but those are properties of the legs and the combo orderbook, not of RFS.

## End-to-end flow

```
Taker                  Exchange                          Makers / market
  │                       │                                │
  │── submit RFS ────────▶│                                │
  │                       │── derive comboSymbol           │
  │                       │── create contract if novel     │
  │                       │   (reuse if it already exists) │
  │                       │── announce on requestForStream ▶│
  │                                                        │
  │       ════════════════════════════════════════════════ │
  │       From here: standard combo orderbook              │
  │       ════════════════════════════════════════════════ │
  │                                                        │
  │── post orders ─────────────────────────────────────────│── makers post orders ──┐
  │                                                                                 ▼
  │                                  orderbook on `comboSymbol`                     │
  │                            (depth, trade tape, account events)                  │
  │── aggressive order ────────── fills ────────────────────────────────────────────│
```

The RFS-specific surface is everything above the double line. Below the double line, integrators use the same WebSocket channels, REST endpoints, and FIX messages they already use for any other Predictions instrument.

## Surface map: what's where

| Concern | Surface |
|---|---|
| Submit a request for liquidity (creating the contract if novel) | `POST /v1/prediction-markets/combos/rfs`, or an `rfs` block on `POST /v1/prediction-markets/combos` (REST). FIX `QuoteRequest` is planned. |
| Discover requests as they come in | [`requestForStream`](/prediction-markets/combos-rfs/websocket-streams#requestforstream) WebSocket channel |
| Post orders on a combo book | Standard order entry against `comboSymbol` |
| See bid/ask, depth, last trade for the combo | `{comboSymbol}@bookTicker`, `{comboSymbol}@depth*`, `{comboSymbol}@trade` |
| Your own order/fill/position events | `orders@account`, `positions@account` (authenticated, standard) |
| Halts, resumes, status changes | `contractStatus` (standard) |
| Settlement / clearing | Standard combo settlement ([Combo Contracts](/prediction-markets/combo-contracts/overview#settlement)) |

## Guarantees on the RFS-specific surface

These are the contracts the RFS-specific surface commits to. Broader orderbook guarantees (atomic multi-leg execution, no last look, no order TTL, cancel-on-disconnect, self-trade prevention) come from the standard combo orderbook and apply to combos however they were created.

1. **One endpoint, every asset class.** Crypto, sports, macro, weather, and cross-class leg sets post to the same endpoint with the same payload.
2. **Deterministic combo symbol; no fragmentation.** The same leg set always produces the same `comboSymbol`. A request for a leg set that already has a contract reuses it and re-solicits liquidity rather than opening a parallel book.
3. **Same identifiers across surfaces.** `rfsId` is identical on REST and WebSocket (and FIX `QuoteReqID` when that surface ships). `comboSymbol` is identical everywhere from announcement forward.
4. **Public, anonymous announcement.** `requestForStream` carries no taker identity, and the broadcast strips the RFS's internal-only fields. Makers see **what was requested** — legs, indicative side and size, structure classification — and **not who is requesting it**. The signal is "the market has this demand," not "this trader wants this." Anyone can subscribe.
5. **Standard combo treatment.** A combo behaves identically whether it was pre-listed or created by an RFS — same fee schedule, margin, settlement, and halt behavior. The `CMB` ticker prefix is the only identifier needed to recognize a combo; downstream tools don't need a separate "how did this combo originate?" signal.
6. **Idle housekeeping.** A combo that attracts no resting interest for an extended idle window may be delisted by housekeeping. This is a property of the combo contract lifecycle, not of RFS; it applies to combos that were spun up on demand and never gained traction. Pre-listed combos may be retained by curation policy — see [Combo Contracts](/prediction-markets/combo-contracts/overview).

## Glossary

| Term | Meaning |
|---|---|
| **RFS** | Request-for-Stream. A request for liquidity on a combo, creating the contract first if the leg set doesn't have one yet. |
| **`rfsId`** | Globally unique (UUID) identifier for one RFS submission, shared across REST and WebSocket (and FIX `QuoteReqID` when that surface ships). |
| **`comboSymbol`** | The derived combo instrument ticker, content-addressable from the leg set. Used to interact with the resulting orderbook everywhere. |
| **`RFSSummary`** | The persisted RFS record returned by the create endpoints (under `request` or `rfs`) and mirrored on the broadcast. See the [Reference](/prediction-markets/combos-rfs/reference#rfssummary). |
| **Discovery feed** | The public `requestForStream` WebSocket channel that announces incoming requests so makers can come quote. |

## Open questions

1. **Server-side discovery filtering (PREDICT-4732).** At v0.1 the `requestForStream` channel broadcasts every event and makers filter client-side; `assetClasses` is derived but currently always empty. The categories rework will populate `assetClasses` and add server-side subset/structure filtering so makers receive only requests they want to price.
2. **Cross-class structure handling.** Whether risk/margin treatment differs from same-class combos, and how cross-class structures surface once server-side filtering lands.
3. **Housekeeping windows.** Per-asset-class idle durations before an idle combo is delisted (and whether pre-listed combos are exempt).
4. **FIX surface.** A FIX `QuoteRequest`-based entry point (`rfsId` ↔ `QuoteReqID`) is planned but not part of this release.

Structure-type tagging (`SAME_EVENT`, `CROSS_EVENT`, `BASKET`, `SPREAD`, `CONDITIONAL`, `CROSS_CLASS`, `ANY`) and exchange-derived `eventId` same-event detection are **implemented** — see the [Reference](/prediction-markets/combos-rfs/reference#rfsparams).

## Read next

- [Request & Lifecycle Reference](/prediction-markets/combos-rfs/reference) — the two write endpoints, the `RFSSummary` object, and the request-vs-contract lifecycle.
- [WebSocket Reference](/prediction-markets/combos-rfs/websocket-streams) — `requestForStream` plus the handoff to standard combo channels, with maker and taker flows.
- [Maker Integration](/prediction-markets/combos-rfs/maker-economics) — discovery filters and rewards integration.
- [Examples](/prediction-markets/combos-rfs/examples) — crypto spread (full REST/WS/FIX), sports SGP, and cross-class basket.
- [Combo Contracts](/prediction-markets/combo-contracts/overview) — orderbook behavior, ticker format, and settlement that apply to every combo on the venue.