Realtime protocol

Tayho realtime delivers snapshots and at-least-once events. Use it to refresh interfaces quickly, while REST reads and receipt status remain the durable lifecycle authority.

Connect

Send POST /v1/realtime/tickets with an API key granting realtime.
Open wss://<api-host>/v1/ws?ticket=<ticket> before expiresAt.
Use each ticket once. Obtain a new one for every connection or reconnect.
Wait for hello, then send subscribe.

Never put the API key in the WebSocket URL. A consumed, expired, or invalid ticket is rejected.

{
  "type": "subscribe",
  "requestId": "subscribe-portfolio-1",
  "channels": [
    "market.price:7",
    "trader.positions:0x1111111111111111111111111111111111111111"
  ]
}

The server returns an authoritative snapshot for a new channel, then a subscribed acknowledgement. Events can overlap state already represented by the snapshot.

Channel catalog

Family	Allowed values
Protocol	`protocol.config`, `vault.state`, `staking.state`, `system.status`
Market	`market.{state\|price\|trades\|funding\|liquidity\|oracle}:<marketId>`
Trader	`trader.{positions\|portfolio\|balances\|activity\|orders\|trades\|funding\|settlements\|sessions\|vault\|rewards\|transfers}:<address>`
Lifecycle	`intent:<orderHash>`, `action:<actionHash>`, `transaction:<txHash>`

Addresses and hashes are canonicalized to lowercase. Market IDs are canonical unsigned decimal values. Protected intent: and action: snapshots require the matching receipt in the capabilities object:

{
  "type": "subscribe",
  "requestId": "subscribe-action-1",
  "channels": [
    "action:0x1111111111111111111111111111111111111111111111111111111111111111"
  ],
  "capabilities": {
    "action:0x1111111111111111111111111111111111111111111111111111111111111111": "receipt-capability"
  }
}

Delivery rules

An event includes a stable eventId, one or more channels, a stream sequence, source, timestamp, optional checkpoint, and domain data. Delivery is at least once:

deduplicate by eventId;
apply domain versions or sequences monotonically;
persist only the latest sequence per subscribed channel; and
reconcile from REST after any uncertain period.

The server sends heartbeat; clients can send ping and receive pong. Client message types are subscribe, unsubscribe, and ping. Server message types are hello, snapshot, event, subscribed, unsubscribed, heartbeat, pong, resync_required, and error.

Reconnect and resume

On reconnect, obtain a new ticket and include each saved channel cursor:

{
  "type": "subscribe",
  "requestId": "resume-portfolio-2",
  "channels": ["market.price:7"],
  "resumeFrom": {
    "market.price:7": "1784203200000-0"
  }
}

The server replays later matching events when they remain available. If the replay has a gap or is too large, it sends resync_required and follows with a fresh snapshot. Replace local channel state from that snapshot and continue with its sequence. Use exponential backoff with jitter for repeated connection failures. The Tayho SDK automatically obtains fresh tickets, reconnects, resumes channel cursors, and keeps a rolling event-ID deduplication window.

Errors and closure

Protocol errors include a stable code and can identify the affected request or channel. INVALID_CHANNEL, SUBSCRIPTION_LIMIT, CAPABILITY_REQUIRED, CAPABILITY_INVALID, and REALTIME_UNAVAILABLE require the caller to correct input or reconcile. Connection or message admission failures can close the socket; respect the HTTP or close reason and avoid reconnect storms. The complete message schemas are available in the generated realtime reference.

​Realtime protocol

​Connect

​Channel catalog

​Delivery rules

​Reconnect and resume

​Errors and closure