Sigil exposes a WebSocket endpoint for live event subscriptions. Connect to wss://rpc.sigil.ml/ws and use the JSON-RPC sigil_subscribe / sigil_unsubscribe methods.

​
Connection

const ws = new WebSocket("wss://rpc.sigil.ml/ws");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "sigil_subscribe",
    params: { topic: "newBlock" }
  }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
});
The server returns a subscription id in the response: 
{ "jsonrpc": "2.0", "id": 1, "result": "sub_abc123" }
Subsequent events arrive as notifications: 
{
  "jsonrpc": "2.0",
  "method": "sigil_subscription",
  "params": { "subscription": "sub_abc123", "result": { /* event */ } }
}

​
Topics

TopicPayload
newBlockBlock header, height, state root, transaction hashes.
newTxMempool admission notice. Includes envelope hash and originator DID.
consensusMACA round state and Tower epoch locks.
consensus.finalisedPer-block finalisation event.
consensus.epoch_lockedPer-epoch Tower lock event.
validatorsActive set changes.
dexDEX pool updates filtered by pool id.
nftNFT mint, transfer, and burn events filtered by collection.
mailMailbox delivery events filtered by recipient DID.
vigilsVigil delivery events filtered by subscription id.

​
Filtered subscriptions

Most topics accept a filter parameter: 
{
  "jsonrpc": "2.0", "id": 1,
  "method": "sigil_subscribe",
  "params": {
    "topic": "dex",
    "filter": { "pool_id": "0xabc..." }
  }
}
Filter shape varies per topic; consult the topic’s reference page.

​
Unsubscribing

{
  "jsonrpc": "2.0", "id": 2,
  "method": "sigil_unsubscribe",
  "params": { "subscription": "sub_abc123" }
}
Closing the WebSocket also drops all subscriptions on that connection.

​
Backpressure and limits

LimitValue
Subscriptions per connection100
Concurrent connections per IP32
Outbound queue per subscription1,024 events
If the outbound queue overflows, the server emits an overflow notification and drops the subscription. Clients should handle the drop and re-subscribe.

​
Authenticated subscriptions

Identity-bound subscriptions (e.g. private mailbox event streams) are served on the /ws-private endpoint and require a JWT issued under authentication. See the private WebSocket runbook for the operator configuration.

​
Resilience

Subscriptions survive transient block production gaps but do not survive epoch boundaries in archive mode. Clients should treat consensus.epoch_locked as a checkpoint to persist the last-seen height and resume from there after reconnect.