Subscriptions Format

Subscribing

> {"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": [ "block" ]}

< {"jsonrpc": "2.0", "id": 1, "result": "242d29d5c0ec9268f51a39aba4ed6a36c757c03c183633568edb0531658a9799"}

This sends a JSON-RPC request with method subscribe and params describing events you are subscribing to, with a locally generated id. The server will respond to the subscription request, include your locally generated id and provide its own unique id.

Request Format

Field Name	Type	Description
jsonrpc	`string`	A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
method	`string`	A String containing the name of the method to be invoked: `subscribe` or `unsubscribe`.
params	`array`	An array with 1-2 elements. The first argument to subscribe is always a string describing the subscription event type, e.g. `block`. The second argument is optional depending on event type, but if present is an object.
id	`number`	An identifier established by the Client that MUST contain a String, Number, or NULL value if included.

Note: It's the responsibility of the client to map their locally generated id to the server generated id.

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": [
    "block",
    {
      "number": 7280000
    }
  ]
}

Subscription Response Format

Field Name	Type	Description
id	`string`	The locally generated id from from the initial request.
result	`string`	A server-generated id which will be appended to all push messages related to this subscription.
metadata	`object`\|`string`	Any additional data that pertains to a specific subscription.

Example:

{
  "jsonrpc": "2.0", 
  "id": 1, 
  "result": "242d29d5c0ec9268f51a39aba4ed6a36c757c03c183633568edb0531658a9799"
}

Subscription Notification Format

Field Name	Type	Description
params	`object`	An `object` containing the `result` and `subscription`.
result	`object`	The event notification details.
subscription	`string`	The server id from the initial request/response.

Example:

{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
    "result": {
      "blockchainId": "1c9c969065fcd1cf",
      "number": 7452758,
      "hash": "0x087ad0362e03cc781b2f252333d68caa52575bc72976d6350d7608561c57770a",
      ...
    },
    "subscription": "e0b0f42177341bff16987e1b12904d7dc8a6e4417dee0291fa134b5044763482"
  }
}

Unsubscribing

To stop receiving subscription notifications simply provide the subscription id with the unsubscribe method and you'll no longer receive notifications of those events. The result that comes back will be true if an unsubscribe event actually occurred (i.e., you passed a valid subscription id).

Example:

> { "jsonrpc": "2.0", "method": "unsubscribe", "params": [ "242d29d5c0ec9268f51a39aba4ed6a36c757c03c183633568edb0531658a9799" ], "id": 1 }

< { "jsonrpc": "2.0", "id": 1, "result": true}