Gas Fee (Real-time)

Receive real-time gas fee updates via WebSocket. The server broadcasts the current network gas fee at regular intervals through a cron job. Clients subscribe to the broadcast:gas_fee channel and receive updates automatically.

Connection

1. Connect to the Realtime Server

Establish a Socket.IO connection with a valid JWT token:

import { io } from "socket.io-client";

const socket = io("wss://realtime.example.com", {
  auth: {
    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  },
});

2. Subscribe to the Gas Fee Channel

Once connected, emit a subscribe event with the channel name broadcast:gas_fee:

socket.on("connect", () => {
  socket.emit("subscribe", "broadcast:gas_fee");
});

3. Listen for Messages

Gas fee updates arrive as message events. Check the type field to identify gas fee messages:

socket.on("message", (data) => {
  if (data.type === "gas_fee") {
    console.log("Gas Fee Update:", data.payload);
    // {
    //   chainId: 137,
    //   maxPriorityFee: 0.000000030,
    //   maxFee: 0.000000034,
    //   nativeCurrencySymbol: "POL"
    // }
  }
});

4. Unsubscribe (optional)

socket.emit("unsubscribe", "broadcast:gas_fee");

Full Example

import { io } from "socket.io-client";

const REALTIME_URL = "wss://realtime.example.com";
const GAS_FEE_CHANNEL = "broadcast:gas_fee";

const socket = io(REALTIME_URL, {
  auth: { token: "<your_jwt_token>" },
});

socket.on("connect", () => {
  console.log("Connected:", socket.id);
  socket.emit("subscribe", GAS_FEE_CHANNEL);
});

socket.on("message", (data) => {
  if (data.type === "gas_fee") {
    const { chainId, maxPriorityFee, maxFee, nativeCurrencySymbol } = data.payload;
    console.log(`Gas Fee: ~${maxFee} ${nativeCurrencySymbol} (Chain ${chainId})`);
  }
});

socket.on("error", (err) => {
  console.error("Socket error:", err);
});

socket.on("disconnect", () => {
  console.log("Disconnected");
});

Message Format

Each message received from the broadcast:gas_fee channel has the following envelope structure:

{
  "type": "gas_fee",
  "payload": {
    "chainId": 137,
    "maxPriorityFee": 0.000000030,
    "maxFee": 0.000000034,
    "nativeCurrencySymbol": "POL"
  },
  "timestamp": "2026-02-28T14:30:00Z"
}

Envelope Fields

Field	Type	Description
type	string	Message type identifier. Always gas_fee for this channel
payload	object	Gas fee data
timestamp	string	ISO 8601 timestamp of when the message was published

Payload Fields

Field	Type	Description
chainId	integer	The chain ID of the active network (e.g., 1 = Ethereum, 137 = Polygon)
maxPriorityFee	number	Maximum priority fee (tip) per gas unit, in native currency
maxFee	number	Maximum total fee per gas unit (base fee + priority fee + buffer), in native currency
nativeCurrencySymbol	string	Symbol of the chain's native currency (e.g., POL, ETH)

Channel Reference

Channel	Description
broadcast:gas_fee	Public channel — all authenticated users can subscribe

info

Broadcast channels (prefixed with broadcast:) are public and available to all authenticated users. User-specific channels require the user's ID in the channel name.

Notes

• Gas fee values are in the chain's native currency (not Gwei). To convert to Gwei, multiply by 1,000,000,000.
• Updates are pushed periodically by a server-side cron job — clients do not need to poll.
• The connection requires a valid JWT token. Expired tokens will result in an Authentication error.

Environments

Test: https://test-socket.tokenizationtr.com