Stream Quickstart

---

What is Nodit Stream?

Nodit Stream is a service that lets you subscribe to on-chain events from multiple networks through a bidirectional stream channel and receive them in real time. It uses the same event types as Nodit Webhook, allowing you to filter the data you need. Unlike Webhook, however, Stream delivers events over a synchronized WebSocket channel rather than an asynchronous channel.

Nodit Stream Endpoint

The WebSocket endpoint for Nodit Stream is as follows.

• wss://web3.nodit.io/v1/websocket

:::info Is the wss feature provided by Stream different from the one provided by the Node service? Yes. The WSS Endpoint shown on each network card in the Nodit Console is used for the Node client's built-in WebSocket communication. The Stream service, like the Web3 Data API, subscribes to curated data through a separate WebSocket server built by the Nodit team. Regardless of the target network, you can use Stream through a single endpoint. :::

Stream Tutorials

1. Environment Setup

This example uses JavaScript to implement a WebSocket connection. Complete the following prerequisites before running the example.

1-1. Install Node.js

Node.js is a JavaScript runtime that supports running various JS applications. Click the link below to install Node.js. Multiple versions are available, but the latest LTS version is recommended for stability.

• Install Node.js\
  

1-2. Install socket.io-client

socket.io-client is a library for real-time WebSocket-based communication on the client side. Use it to connect to a server and send/receive real-time data and events. If Node.js is installed, you can install it easily using the terminal. Run the command below in the terminal at the root directory where you want to implement the WebSocket.

npm install socket.io-client

1-3. Sign Up for Nodit Console

Nodit provides a Node service for connecting to various blockchain networks. Click the link below to access the Nodit Console and create an account.

• Go to Nodit Console

1-4. API Key

Copy the API key generated on the project Overview page and store it in a safe location.

2. Writing the Code

In this example, you will write code that subscribes to the BLOCK_PERIOD event using a WebSocket and receives a notification each time a new block is created. Enter the required values for a few variables in the sample code below. These variables play an important role in configuring the WebSocket code to operate correctly and securely. Replace the placeholder values with the appropriate data for your environment.

• messageId: A unique identifier for the WebSocket message. Replace this with an actual ID relevant to your application. The message ID is used to distinguish specific messages or events between the server and client.
• description: A brief description of the purpose of the WebSocket connection. Replace this with a description that reflects the actual use of the connection. This description helps identify the connection easily during service logging, monitoring, or troubleshooting.
• apiKey: Replace this with the actual API key provided in the Nodit Console. The API key is essential for secure access to the service and for verifying user authentication.
• protocol: Represents the blockchain protocol you are interacting with. Replace this with a specific protocol name such as "Ethereum" or "Arbitrum". The protocol defines which blockchain technology the WebSocket connection interacts with.
• network: Specifies the target network. Replace this with a specific network such as "mainnet", "testnet", or "sepolia". The network designates the specific environment within the protocol where actual data is transmitted.

import io from "socket.io-client";

// {Your websocket message ID} - This is a unique identifier for your WebSocket message. You need to replace this placeholder with an actual ID that is relevant to your application.
const messageId = "{Your websocket message ID}"; 

// eventType specifies the type of event you want to subscribe to on the blockchain. For example, "BLOCK_PERIOD" could be used to receive events related to blockchain block timings.
const eventType = "BLOCK_PERIOD";

// The WebSocket URL to connect to. You need to use the appropriate URL provided by your blockchain service provider.
const url = "wss://web3.nodit.io/v1/websocket";

// Parameters for configuring the subscription. You should replace the placeholder in 'description' with a brief description of your WebSocket connection's purpose.
const params = {
  description: "{description about your websocket}",
  condition: {
    period: 1 // You can set this to any integer greater than zero. This could be used to specify the frequency of events, such as receiving an event every 'n' blocks.
  }
};

// Options for the WebSocket connection. These include security settings and additional parameters required by the server.
const options = {
  rejectUnauthorized: false, // This should be true in production for better security unless your server uses a self-signed certificate.
  transports: ["websocket"],
  path: "/v1/websocket/",
  auth: {
      apiKey: "{Your Api Key}", // Replace this with your actual API key provided by the service.
  },
  query: {
      protocol: "{protocol}", // Replace this with the blockchain protocol you are interacting with, e.g., "ethereum", "arbitrum", etc.
      network: "{network}", // Replace this with the specific network you are targeting, e.g., "mainnet", "testnet".
  },
};

// This function establishes a connection to the server and handles various WebSocket events.
function connectToServer() {
  return new Promise((resolve, reject) => {
    const socket = io(url, options);

    socket.on("connect", () => {
      socket.on("subscription_registered", (message) => {
        console.log("registered", message);
      });

      socket.on("subscription_connected", (message) => {
        console.log("subscription_connected", message);

        // Emit a subscription message with your specific messageId, eventType, and parameters.
        socket.emit("subscription", messageId, eventType, JSON.stringify(params));
      });

      socket.on("subscription_error", (message) => {
        console.error(`nodit_subscription_error: ${message}`);
      });

      socket.on("subscription_event", (message) => {
        console.log("subscription Event : ", message);
      });

      socket.on("disconnect", (message) => {
        console.warn(`disconnect`, message);
      });

      resolve(socket);
    });

    socket.on("connect_error", (error) => {
      console.error(`Socket connection error to : `, error);
      reject(error);
    });
  });
}

connectToServer();

3. Running and Verifying the Response

Once the code is written as shown above, run the file using the terminal and Node.js.

node your_file_name.js

After running the code, if the WebSocket successfully connects to the Ethereum network, you will receive events like the following each time a new block is created.

subscriptionId: 97139
subscription Event :
  eventType: "BLOCK_PERIOD",
  event: {
    "period":1,
    "message":{
      "number":17767702,
      "hash":"0x836c2ada70123019592fc52763757c87061935bbab2609d2dac1d0e9a93a6186",
      "parent_hash":"0xc8936f4c504b1640df7e1c920dbd1879a0906c7d44cf369d7f26b2939bfa2864",
      "nonce":"0x0000000000000000",
      "sha3_uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "logs_bloom":"0x1d374002c00c144a39093818900082b050884050220a14960209123380de5e80c4581182411812b173505850b0b5818112ad99b88dcf39abc651fc95d5ed2b04649070b87fa209ccbe23c02fc829b16c9c804020016e0c8b20805f42cc611800da80041507d304350971a2476d921a8db9934bcc290e0549d68d13f014082f062e3a92d03692002012d0704842a08800f9050d835910246c56aa4153a81134308ef82dc47101fec2601329e7f05414a2860c003f226d86ee8221276610108c5d89548da24018c10e261ca6422096378c0d7903076328129800d520868a11e846c1ffb1a904c68590034524c47c818c2480e137be5b1e44e268198af3b6023d89",
      "transactions_root":"0xed72506de019800931029aa7f4efdb255b9a6c2ebab2751afd98e3d2875e4159",
      "state_root":"0x35ee38917ecf6a96f9512690b4717002f233dd0dfe08f404097c0eff91f4aa20",
      "receipts_root":"0x59f4b1fc17aa8e408eec5377f4b37314333476229b350fe4b4549868ba8c7fdc",
      "miner":"0x1f9090aae28b8a3dceadf281b0f12828e676c326",
      "difficulty":0,
      "total_difficulty":5.875000371659836e+22,
      "size":58801,
      "extra_data":"0x7273796e632d6275696c6465722e78797a",
      "gas_limit":30000000,
      "gas_used":11663189,
      "timestamp":1690258955,
      "transaction_count":107,
      "base_fee_per_gas":17895212572
    }
  }

:::info 📘 View more detailed WebSocket call code examples

The Nodit Developer Portal provides Recipes with more detailed WebSocket call code examples. Click the link below to explore them.

▶︎ View WebSocket Recipe :::