> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convallax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quote Request Stream

> Server-Sent Events stream that pushes live quote requests to market makers. Authenticated via the X-API-Key header.

Subscribe to the maker quote-request stream over **Server-Sent Events**. This is channel 1 of the [three-channel maker transport](/guides/market-maker) — it pushes a `connected` event, an initial snapshot of open requests, and then live `quote_request` / `quote_request_expired` events. See the [Quote Request Stream guide](/guides/quote-stream) for the full walkthrough.

The response has `Content-Type: text/event-stream`. Use the browser `EventSource` API or any SSE-capable client.

## Authentication

Provide your **per-MM API key** in the `X-API-Key` header:

```
X-API-Key: <your-key>
```

If your client cannot set custom headers, pass `?apiKey=<your-key>` as a query parameter instead.

## Headers

<ParamField header="X-API-Key" type="string" required>
  Your per-MM API key (or pass `?apiKey=` as a query parameter).
</ParamField>

<ParamField header="Last-Event-ID" type="string">
  The last SSE event `id` you processed. On reconnect, the server replays events after this id if they are still in the buffer; otherwise it falls back to a fresh snapshot. The browser `EventSource` API sets this automatically.
</ParamField>

## Events

<ResponseField name="connected" type="event">
  Sent once on connect. Data: `{ "makerId": "mm-alpha", "serverTime": "<iso>" }`.
</ResponseField>

<ResponseField name="snapshot_begin" type="event">
  Marks the start of the initial snapshot of open requests. Data: `{}`.
</ResponseField>

<ResponseField name="quote_request" type="event">
  A new (or replayed/snapshot) quote request. Each carries an SSE `id:` (monotonic integer). Data contains `requestId`, `expiresAt`, and `params` (`wallet`, `market`, `option`, `trade`).
</ResponseField>

<ResponseField name="snapshot_complete" type="event">
  Marks the end of the initial snapshot. Data: `{}`. Live events follow.
</ResponseField>

<ResponseField name="quote_request_expired" type="event">
  A request closed (committed, expired, or cancelled). Data: `{ "requestId": "req-789" }`.
</ResponseField>

## `quote_request` Data Fields

| Field                       | Type          | Description                                                                                                                                              |
| --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId`                 | string        | Unique ID for this quote request — use it when you `POST /v1/mm/quotes`                                                                                  |
| `expiresAt`                 | string        | ISO 8601 expiry time for the quote request (default 5 min TTL)                                                                                           |
| `params.wallet`             | string        | Taker wallet address (may be `null` if not yet provided)                                                                                                 |
| `params.market.conditionId` | string        | Polymarket condition ID (bytes32)                                                                                                                        |
| `params.market.yesTokenId`  | string        | Polymarket YES CLOB token ID                                                                                                                             |
| `params.market.question`    | string        | Human-readable market question                                                                                                                           |
| `params.option.optionType`  | string/number | `"call"` or `"put"` (or `0`/`1`)                                                                                                                         |
| `params.option.strikeBps`   | number        | Strike in basis points of \$1                                                                                                                            |
| `params.option.expiryMs`    | number        | Option expiry (Unix ms)                                                                                                                                  |
| `params.trade.side`         | string        | `"buy"` or `"sell"` (taker's side)                                                                                                                       |
| `params.trade.budgetUsd`    | number        | **Buys only.** USDC the taker will spend (their premium budget). The fill is `floor(budgetUsd / yourPrice)` whole options, capped by your quoted `size`. |
| `params.trade.size`         | number        | **Sells only.** Number of whole options the taker wants to write.                                                                                        |

<Info>
  On a **buy**, the taker enters a USDC amount, not a contract count — so the request carries `trade.budgetUsd` and **no** `trade.size`. You quote a **per-option price**; the number of options the taker receives is `floor(budgetUsd / price)`. Size your collateral accordingly: `floor(budgetUsd / price) × (1 − K)` for a call, `× K` for a put.
</Info>

<Info>
  Keep-alive: the server sends SSE comment lines (`: ping`) about every 25 seconds. SSE clients ignore them automatically.
</Info>

<RequestExample>
  ```bash theme={null}
  curl -N https://api.convallax.com/v1/mm/quote-requests/stream \
    -H "X-API-Key: mk_live_alpha_xxx"
  ```
</RequestExample>

<ResponseExample>
  ```text Stream theme={null}
  event: connected
  data: {"makerId":"mm-alpha","serverTime":"2026-06-15T12:00:00.000Z"}

  event: snapshot_begin
  data: {}

  event: snapshot_complete
  data: {}

  event: quote_request
  id: 1043
  data: {"requestId":"req-789","expiresAt":"2026-06-15T12:05:00.000Z","params":{"wallet":"0xTrader...","market":{"conditionId":"0xa4ddc188...","yesTokenId":"51508280778...","question":"Will there be a Hantavirus outbreak in 2026?"},"option":{"optionType":"call","strikeBps":50,"expiryMs":1735689600000},"trade":{"side":"buy","budgetUsd":100}}}

  event: quote_request_expired
  data: {"requestId":"req-789"}
  ```
</ResponseExample>