Live order updates

WebSockets make an order screen feel immediate, but they are an accelerator—not the durable source of truth. Keep an owner-authorized REST read and poll it after reconnects or missed frames.

Upgrade routes

Order type	WebSocket upgrade
Swap	GET /v2/swaps/{id}/events
Native bridge	GET /v2/bridges/{id}/events

These upgrade routes are intentionally outside the HTTP OpenAPI document. Their payload contains the same current order snapshot returned by the corresponding REST read. The exact machine-readable channel and frame schemas are at GET /v2/asyncapi.

Authenticate the connection

Browser WebSockets cannot set x-session-id. Use the exact destination address as the read-only verify query value:

wss://api-beta.wagyu.xyz/v2/swaps/<order-id>/events?verify=<exact-destination-address>

Non-browser clients may use the owner x-session-id header. Never put a session ID in a WebSocket URL. Missing, unauthorized, and nonexistent orders all close with the same opaque 4404 code, so a failed connection must not be used as an existence check.

Frame contract

The server sends a complete current snapshot immediately after connection, after order changes, and periodically as a missed-event safety net:

{ "orderId": "…", "product": "swap", "status": "processing" }

Frames are snapshots, not patches. They can be repeated or coalesced, and clients send no application messages on these per-order sockets.

Treat each frame as a hint to refresh the owner-authorized REST order. This makes the UI correct even if a reconnect, browser sleep, proxy, or transient server error drops a frame. After every reconnect, perform an authorized REST read before treating the UI as current.

Machine contract

curl https://api-beta.wagyu.xyz/v2/asyncapi

The document has separate route-specific schemas for swap frames and bridge frames. It also defines both valid proof alternatives and the opaque 4404 close behavior.