Subscription API Quickstart

What are WebSockets?

The WebSockets (WSS) communication protocol enables two-way communication between a client and a server over a single TCP connection. The communication protocol maintains a network connection between the two parties, allowing for real-time, low-latency communication. WebSockets allow for ongoing, bidirectional communication unlike HTTP, which is a request-response protocol.

Subscriptions over WebSockets

WebSockets allow you to create stateful subscriptions, which is a type of subscription where the server maintains a record of the client's subscription state. This means that the server remembers what data the client has requested and sent previously, and only sends new data that has changed or meets the client's subscription criteria.

You can create stateful subscriptions over WebSockets to subscribe to specific events on the blockchain. The following subscription methods are available:

• eth_subscribe - Create a subscription to a particular event
• eth_unsubscribe - Cancel an active subscription

Supported networks

Supported chains: ETH, ETC, BSC, KCC.

Subscription API Endpoints

Below are the subscription endpoints available and the corresponding docs for each of them.

Subscription Type	Description
tokenview_pendingTransactions	Emits full transaction objects or hashes that are sent to the network, marked as "pending", based on provided filters.
newPendingTransactions	Emits transaction hashes that are sent to the network and marked as "pending".
newHeads	Emits new blocks that are added to the blockchain.
logs	Emits logs attached to a new block that match certain topic filters.

eth_subscribe

Creates a new subscription for particular events. The node returns a subscription ID. For each event that matches the subscription, a notification with relevant data is sent together with the subscription ID.

Parameters

Specify the subscription event parameters, including the following:

• newHeads: Subscribing to this returns a notification each time a new header is appended to the chain, including chain reorganizations. In a chain reorganization, the subscription emits all new headers for the new chain. Therefore the subscription can emit multiple headers at the same height.

• logs: Returns logs that are included in new imported blocks and match the given filter criteria. In case of a chain reorganization, previously sent logs that are on the old chain are resent with the removed property set to true. Logs from transactions that ended up in the new chain are emitted. Therefore a subscription can emit logs for the same transaction multiple times. This parameter has the following fields:

  • address: (optional) Either an address or an array of addresses. Only logs that are created from these addresses are returned.
  • topics: (optional) Only logs that match these specified topics are returned.

  ❗️ We strongly recommend specifying a filter (address or topics or both) when subscribing to the logs event.

• newPendingTransactions: Returns the hash for all transactions that are added to the pending state and are signed with a key that's available in the node. When a transaction that was previously part of the canonical chain isn't part of the new canonical chain after a reorganization, it's emitted again.

• okenview_pendingTransactions: subscribes to pending transactions via WebSockets, and filters those transactions based on specified from and/or to addresses. The subscription will return either full transaction objects or just transaction hashes depending on the request. It will also optionally include re-orged or removed transactions if specified.

Returns

• subscription ID: The ID of the newly created subscription on the node.

Considerations

1. Notifications are sent for current events and not for past events. For use cases that cannot afford to miss any notifications, subscriptions are probably not the best option.
2. Subscriptions are coupled to a connection. If the connection is closed all subscriptions that are created over this connection are removed.
3. Notifications are stored in an internal buffer and sent from this buffer to the client. If the client is unable to keep up and the number of buffered notifications reaches a limit (currently 10k) the connection is closed. Keep in mind that subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.

eth_unsubscribe

Cancel subscriptions by calling this method with the subscription ID. It returns a boolean indicating that the subscription was canceled successfully.

Parameters

• subscription ID : The ID of the subscription you want to unsubscribe.

Returns

• unsubscribed flag : (boolean) True if the subscription is canceled successfully.

Example

Request

wscat -c wss://services.tokenview.io/vipapi/websocket/node/{network}/{apikey} -x '{"jsonrpc":"2.0", "id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]}'

Response

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