Order status stream (SSE)

Endpoint

GET https://api.vane.xyz/api/orders/{orderUUID}/status-stream

This is the one path in the API without the /v1 prefix; adding it returns 404. No authentication is required, since the order UUID is the credential. A browser EventSource sends an Origin header, and the API answers 500 for any origin outside vane.xyz and localhost, so a page on another domain opens the stream through its own backend.

Contract

Behavior	Detail
Response	`200` with `Content-Type: text/event-stream` and one empty line. The connection stays open until 60 seconds pass without an event, then the server closes it.
Snapshot on connect	None. Fetch `GET /v1/orders/{uuid}` first for the current state.
Heartbeat	None. Silence between transitions is normal, but the server drops any connection that has been silent for 60 seconds, and each event restarts that clock. Expect to reconnect about every minute while an order waits for its deposit.
Unknown UUID	Still `200`. The stream opens and never emits, so validate by fetching the order first.
Replay	None. Events carry an `id:` (the `updatedAt` time in Unix milliseconds) and `retry: 5000`, but a reconnect with `Last-Event-ID` replays nothing. Re-fetch the order instead.

Event format

Each transition arrives as one orders:status-update event:

Event stream

event: orders:status-update
id: 1768485912000
retry: 5000
data: {"orderId":"7f9c2e4a-1b3d-4c5e-8f6a-2d9b0c1e3f5a","status":"PROCESSING","message":"order update","updatedAt":"2026-01-15T14:05:12.000Z"}

orderId is the order’s UUID, the same value as in the URL, not the numeric id. status is the state the order just entered, message is the fixed label order update, and updatedAt is an ISO 8601 UTC timestamp. The id: line repeats updatedAt in Unix milliseconds, and retry: 5000 tells EventSource to wait 5 seconds before reconnecting. The event name contains a colon, so listen with addEventListener("orders:status-update", ...); onmessage never fires. Amounts and transaction hashes never ride along, so re-fetch the order after each event to read them.

Example

Fetch the order, skip subscribing if it’s already terminal, then open the stream.

UUID=7f9c2e4a-1b3d-4c5e-8f6a-2d9b0c1e3f5a
curl -s https://api.vane.xyz/api/v1/orders/$UUID | jq .status
curl -N https://api.vane.xyz/api/orders/$UUID/status-stream

const api = "https://api.vane.xyz/api";
const uuid = "7f9c2e4a-1b3d-4c5e-8f6a-2d9b0c1e3f5a";
const terminal = new Set(["COMPLETED", "ERROR", "TIMED_OUT"]);

const order = await fetch(`${api}/v1/orders/${uuid}`).then((r) => r.json());

if (!terminal.has(order.status)) {
  const stream = new EventSource(`${api}/orders/${uuid}/status-stream`);
  stream.addEventListener("orders:status-update", async (event) => {
    const { status } = JSON.parse(event.data);
    console.log("now:", status);
    if (terminal.has(status)) stream.close();
  });
}

Reconnecting is part of the contract, since the server closes every idle stream after 60 seconds. EventSource reconnects on its own after the 5 second retry delay the events carry. Raw HTTP clients need a loop that reopens the stream whenever it closes; a read timeout of 70 seconds or more is safe, since the server always closes first. Reconnect and poll-fallback patterns, including why you re-fetch after every reconnect, are in Track orders.

Getting started

Working with orders

Tokens

Orders

Auth

Order status stream (SSE)

Contract

Event format

Example

​Contract

​Event format

​Example

Contract

Event format

Example