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}