Runtime WebSocket

The runtime WebSocket streams selected live resources and serves current runtime queries. Resolve the instance and its resource catalog through REST before connecting.

Connection

Convert the Forge HTTP scheme to its WebSocket equivalent and keep the API prefix:

wss://forge.example.com/api/v1/runtime/ws/instance?instance=signal-watch--0.0.1

The instance parameter is required. Forge resolves the current runtime endpoint; clients do not need an internal process port.

Requests

Every request may include an integer id for correlation.

{"id":1,"method":"SUBSCRIBE","keys":["bar://okx/BTCUSDT@1m"]}
{"id":2,"method":"UNSUBSCRIBE","keys":["bar://okx/BTCUSDT@1m"]}
{"id":3,"method":"LIST"}
{"id":4,"method":"RESYNC","keys":["book://okx/BTCUSDT@full"]}
{"id":5,"method":"QUERY","path":"/resources","params":{}}

SUBSCRIBE and UNSUBSCRIBE accept exact catalog keys. Pattern subscriptions can be supported by the runtime but are unsuitable for clients that need a stable, auditable resource set.

Control responses

A subscription acknowledgment reports success or failure per key:

{
  "type":"ack",
  "id":1,
  "method":"SUBSCRIBE",
  "results":[{"key":"bar://okx/BTCUSDT@1m","code":0,"message":""}]
}

LIST returns type: "list_ack" and the active keys. Protocol errors return type: "error" with id, numeric code, and message.

Runtime queries return:

{"type":"QUERY_RESULT","id":5,"ok":true,"data":{"resources":[]}}

An unsuccessful result has ok: false and an error object. Supported query paths include /resources, /accounts, /portfolios, /events, /accounts/{id}/orders, /accounts/{id}/trades, and /portfolios/{id}/view when the corresponding capability exists.

Data frames

Frames identify their resource with an exact key:

type	Semantics
market/bar	A bar sample with millisecond timestamps and decimal strings.
market/scalar	A factor or scalar sample with timestamp and numeric value.
market/book.snapshot	Complete projected book at a sequence number.
market/book.update	One or more level changes after a snapshot.
market/trade	A normalized market trade event.

Decimal market values are strings where exact decimal representation matters. Do not coerce them to binary floating point in accounting code.

Order-book recovery

Apply a snapshot, then updates in sequence order. When a gap is detected, stop applying deltas and send RESYNC for that book key. The runtime responds with a new market/book.snapshot when a projection is available.

Reconnect behavior

Subscriptions belong to one WebSocket session. After a disconnect:

1. reconnect with bounded exponential backoff;

2. re-fetch runtime status and the resource catalog;

3. replace keys that no longer exist;

4. subscribe again;

5. rebuild book projections from new snapshots.

Do not replay a stale subscription set across a project version or run change without revalidating the catalog.