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

# Stream Cashout Quote

> Subscribe to the live buyback quote and terminal status for a cashout request via Server Sent Events.

Open a Server Sent Events (SSE) stream to follow a [cashout request](/api-reference/quote-service/cashout-create). Because a cashout is offered to a single counterparty market maker, the stream surfaces that MM's buyback quote as the degenerate "best quote". It also sends a terminal `status` frame when the request leaves the `active`/`committing` states.

## Authentication

API key required. Pass your API key in the `X-API-Key` header.

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

A Privy JWT (`Authorization: Bearer <jwt>`) is also accepted — see [Authentication](/guides/authentication).

## Path parameters

<ParamField path="id" type="string" required>
  The cashout request ID (UUID).
</ParamField>

## SSE event types

### `best_quote`

Sent when the MM's buyback quote changes (submitted, replaced, or expired). The `book_seq` increments monotonically so you can detect missed updates. `best_quote` is `null` when there is no live quote.

```json theme={null}
{
  "book_seq": 3,
  "version": 1,
  "best_quote": {
    "id": "q1w2e3r4-5678-90ab-cdef-1234567890ab",
    "market_maker_id": "mm-uuid-1234",
    "buyback_price": 41.5,
    "mm_pays_user": true,
    "valid_until": "2026-06-01T18:45:45.000Z",
    "net_received": 66.25
  }
}
```

<ResponseField name="buyback_price" type="number">The directional buyback `amount` the MM quoted (USDC, ≥ 0), gross of the profit fee.</ResponseField>
<ResponseField name="mm_pays_user" type="boolean">`true` when the MM pays the user (position is in profit); `false` when the user pays the MM.</ResponseField>
<ResponseField name="net_received" type="number">The net cash the user walks away with after the buyback (USDC, ≥ 0) — stake plus/minus the directional amount, net of fees. Present only when computable; omitted otherwise.</ResponseField>

When no quote is live, `best_quote` is `null`:

```json theme={null}
{
  "book_seq": 4,
  "version": 1,
  "best_quote": null
}
```

### `status`

Sent once the request leaves `active`/`committing`, then the stream closes. The `status` is the terminal cashout request state.

```json theme={null}
{
  "status": "committed"
}
```

This is a single event — the stream closes right after it. That's different from the [quote-request stream](/api-reference/quote-service/stream#status), where `status` is followed immediately by a second, more specific terminal event (`committed`, `cancelled`, or `expired`) before the stream closes. The cashout stream skips that second event: `status` alone is the terminal signal here.

| Terminal `status` | Meaning                                                               |
| ----------------- | --------------------------------------------------------------------- |
| `committed`       | Buyback driven on chain; the RFQ becomes `bought_back`.               |
| `declined`        | The MM permanently refused to quote (near decided / unpriceable leg). |
| `expired`         | The request's \~90 s TTL elapsed with no commit.                      |
| `cancelled`       | The request was cancelled.                                            |

## Errors

| Status | Code           | Description                          |
| ------ | -------------- | ------------------------------------ |
| 401    | `UNAUTHORIZED` | Missing or invalid API key.          |
| 403    | `FORBIDDEN`    | You do not own this cashout request. |
| 404    | `NOT_FOUND`    | Cashout request not found.           |

<RequestExample>
  ```bash curl theme={null}
  curl -N https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd/stream \
    -H "X-API-Key: $TOTALIS_API_KEY" \
    -H "Accept: text/event-stream"
  ```

  ```javascript JavaScript theme={null}
  // Native EventSource can't send an X-API-Key header — read the SSE stream
  // with fetch instead (works in browsers and Node 18+).
  async function streamCashout(id, apiKey) {
    const res = await fetch(
      `https://api.totalis.trade/v1/cashout-requests/${id}/stream`,
      { headers: { 'X-API-Key': apiKey, Accept: 'text/event-stream' } }
    );

    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    while (true) {
      const { done, value } = await reader.read();
      if (done) return;
      buffer += decoder.decode(value, { stream: true });

      let sep;
      while ((sep = buffer.indexOf('\n\n')) !== -1) {
        const frame = buffer.slice(0, sep);
        buffer = buffer.slice(sep + 2);
        const event = frame.match(/^event: (.+)$/m)?.[1];
        const data = frame.match(/^data: (.+)$/m)?.[1];
        if (!event || !data) continue;
        const payload = JSON.parse(data);

        if (event === 'best_quote') {
          console.log('Buyback quote:', payload.best_quote);
        } else if (event === 'status') {
          console.log('Terminal:', payload.status);
          return; // the stream closes after the terminal status
        }
      }
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```text SSE stream theme={null}
  event: best_quote
  data: {"book_seq":3,"version":1,"best_quote":{"id":"q1w2e3r4-5678-90ab-cdef-1234567890ab","market_maker_id":"mm-uuid-1234","buyback_price":41.5,"mm_pays_user":true,"valid_until":"2026-06-01T18:45:45.000Z","net_received":66.25}}

  event: status
  data: {"status":"committed"}
  ```
</ResponseExample>