Skip to main content
GET
/
v1
/
cashout-requests
/
{id}
/
stream
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"

// 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
      }
    }
  }
}

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"}
Open a Server Sent Events (SSE) stream to follow a cashout request. 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.

​
Path parameters

​
id
string
required
The cashout request ID (UUID).

​
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. 
{
  "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
  }
}
​
buyback_price
number
The directional buyback amount the MM quoted (USDC, ≥ 0), gross of the profit fee.
​
mm_pays_user
boolean
true when the MM pays the user (position is in profit); false when the user pays the MM.
​
net_received
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.
When no quote is live, best_quote is 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. 
{
  "status": "committed"
}
This is a single event — the stream closes right after it. That’s different from the quote-request stream, 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 statusMeaning
committedBuyback driven on chain; the RFQ becomes bought_back.
declinedThe MM permanently refused to quote (near decided / unpriceable leg).
expiredThe request’s ~90 s TTL elapsed with no commit.
cancelledThe request was cancelled.

​
Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key.
403FORBIDDENYou do not own this cashout request.
404NOT_FOUNDCashout request not found.
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"

// 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
      }
    }
  }
}

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"}