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 NameTypeDescription
jsonrpcstringA String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
methodstringA String containing the name of the method to be invoked: subscribe or unsubscribe.
paramsarrayAn 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.
idnumberAn 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 NameTypeDescription
idstringThe locally generated id from from the initial request.
resultstringA server-generated id which will be appended to all push messages related to this subscription.
metadataobject|stringAny additional data that pertains to a specific subscription.

Example:

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

Subscription Notification Format

Field NameTypeDescription
paramsobjectAn object containing the result and subscription.
resultobjectThe event notification details.
subscriptionstringThe 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}