Websocket API for Blockchain Developers

·

Modern blockchain applications require real-time data streaming to deliver responsive user experiences. The WebSocket API plays a crucial role in enabling instant communication between clients and nodes. This guide explores how developers can leverage WebSocket functionality within the OKTC ecosystem—built on Tendermint Core and the Cosmos SDK—while maintaining full compatibility with Ethereum’s widely adopted PubSub API standards.

By transforming native Tendermint events into Ethereum-compatible formats, OKTC ensures seamless integration for Web3 developers familiar with tools like MetaMask, Ethers.js, or Web3.js. Whether you're building decentralized exchanges, NFT marketplaces, or real-time analytics dashboards, understanding this WebSocket layer is essential.

Establishing a WebSocket Connection

To begin interacting with real-time blockchain data, start by launching the REST server with WebSocket support enabled. Use the --wsport flag during initialization. By default, the WebSocket port is set to 8546, aligning with Ethereum’s standard configuration for consistency across environments.

Once the node is running, connect using any standard WebSocket client such as ws, wscat, or browser-native WebSocket objects. No additional plugins or proprietary libraries are required—just standard Web3 tooling.

👉 Discover how real-time blockchain data can power your next dApp

Creating Subscriptions

Subscriptions are initiated via a standard JSON-RPC call using the eth_subscribe method. This approach mirrors Ethereum’s PubSub specification, ensuring familiarity for developers transitioning from Ethereum-based ecosystems.

Required Parameters

  1. Subscription name – Specifies the type of event stream you want to receive.
  2. Optional arguments – Filter criteria, such as contract addresses or topics, depending on the subscription type.

Upon successful registration, the server returns a unique subscription ID—a hexadecimal string used to manage and cancel the subscription later.

Example: Subscribe to New Block Headers

{
  "id": 1,
  "method": "eth_subscribe",
  "params": ["newHeads"]
}

Response:

{ "id": 1, "result": "0xabc123..." }

This ID (0xabc123...) will be referenced whenever you need to unsubscribe or verify active subscriptions.

Canceling Subscriptions

When your application no longer needs to monitor a particular event stream, clean up resources by calling eth_unsubscribe.

Parameters

  1. Subscription ID – The identifier returned during the eth_subscribe call.

The method returns a boolean: true if the subscription was successfully canceled, false otherwise (e.g., if it never existed or was already canceled).

Example: Unsubscribe from Events

{
  "id": 2,
  "method": "eth_unsubscribe",
  "params": ["0xabc123..."]
}

Response:

{ "id": 2, "result": true }

Properly managing subscriptions prevents memory leaks and improves node performance, especially in long-running services.

Supported Subscription Types

OKTC supports several key subscription types that cover most common use cases in decentralized application development.

newHeads

Triggers a notification every time a new block header is added to the blockchain—including during chain reorganizations. This makes it ideal for tracking block confirmations, syncing light clients, or triggering off-chain processing pipelines.

Parameters

None required.

Use Case Example

A wallet application uses newHeads to update transaction confirmation counters in real time without polling.

Logs

Streams smart contract logs that match specified filter conditions. These logs originate from transactions included in newly imported blocks. During chain reorganizations, logs from reverted blocks are resent with the removed: true flag, while new logs from the canonical chain are emitted normally.

This behavior ensures clients maintain accurate state even after forks—a critical feature for reliable indexing services.

Parameters

An optional JSON object containing:

Example: Monitor ERC-20 Transfers

{
  "id": 3,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x123...",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ]
}

This filters logs matching the ERC-20 Transfer event emitted by a specific token contract.

👉 Learn how event-driven architectures improve dApp responsiveness

newPendingTransactions

Receives hashes of all transactions entering the pending mempool—those not yet included in a block but broadcasted across the network. This is particularly useful for front-running detection, gas optimization tools, or monitoring transaction propagation speed.

Note: After a chain reorganization, transactions that were removed from the canonical chain may reappear in this stream when they return to the pending state.

Parameters

None required.

Practical Application

DEX aggregators use this subscription to detect large swaps before confirmation and adjust routing strategies accordingly.

syncing

Indicates whether the node is currently synchronizing with the network. Returns either:

Parameters

None required.

Why It Matters

Monitoring sync status helps ensure your node serves accurate data—especially important for validators, explorers, and indexing platforms.

Frequently Asked Questions (FAQ)

What is the difference between newHeads and logs subscriptions?

newHeads delivers block header updates regardless of content, while logs provides filtered smart contract events based on address and topic criteria. Use newHeads for general chain activity tracking and logs for contract-specific monitoring.

Can I receive full transaction data via WebSocket?

No—newPendingTransactions only returns transaction hashes. To retrieve full details, use eth_getTransactionByHash via RPC after receiving the hash.

How does OKTC handle chain reorganizations?

During re-orgs, outdated logs are resent with removed: true, and new valid logs are pushed normally. Similarly, previously confirmed blocks may trigger new newHeads events if replaced. This ensures clients can maintain correct state history.

Is there a rate limit on subscriptions?

There is no hard rate limit, but excessive subscriptions may impact node performance. Always unsubscribe when done.

Can I run multiple subscriptions simultaneously?

Yes. You can have concurrent subscriptions to newHeads, logs, and other types. Each receives its own unique ID and event stream.

Does this work with existing Ethereum tooling?

Absolutely. Since OKTC maps Tendermint events to Ethereum’s PubSub format, all standard Web3 libraries (Ethers.js, Web3.js) work out of the box.

👉 See how top dApps leverage real-time blockchain feeds

Core Keywords

With robust WebSocket support and Ethereum-compatible event formatting, OKTC empowers developers to build responsive, event-driven applications that react instantly to on-chain activity—without sacrificing interoperability or performance.