chain_subscribeNewHeads - JSON-RPC Method

Description

Establishes a WebSocket subscription that emits every new block header as it is authored on Enjin Matrix. This method is ideal for wallet notifications, block explorers, indexers, and any workflow that reacts to chain progress in real time.

Parameters

This subscription does not accept parameters.

Returns

Each notification contains:

Field	Type	Description
result.number	string	Block number (hex-encoded)
result.parentHash	string	Hash of the parent block
result.stateRoot	string	State trie root
result.extrinsicsRoot	string	Extrinsics trie root
result.digest	object	Consensus digest logs

Subscription Example

Request (WebSocket)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chain_subscribeNewHeads",
  "params": []
}

Sample Notification

{
  "jsonrpc": "2.0",
  "method": "chain_subscription",
  "params": {
    "subscription": "0x0000000000000000",
    "result": {
      "parentHash": "0xa0ac758e5eb9d474245a06c00882946b5d98c8e1cb5873c5f8234da327fe6c47",
      "number": "0x677b8f",
      "stateRoot": "0xe4afd1f9f7e8f5652cff96d9a45396878b7b4a2f9745ecbfcd5cecb2f4ed9705",
      "extrinsicsRoot": "0x2cecf68ef6d37398a0630c4df5bf43d8da7caa448cf65b76409abfa732df876d",
      "digest": {
        "logs": [
          "0x0661757261201c957a1100000000"
        ]
      }
    }
  }
}

Code Examples

JavaScript (Polkadot.js)

import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

await api.rpc.chain.subscribeNewHeads((header) => {
  console.log(`New block ${header.number.toString()}: ${header.hash.toHex()}`);
});

Node.js WebSocket (Manual)

import WebSocket from 'ws';

const ws = new WebSocket('wss://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'chain_subscribeNewHeads',
    params: []
  }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.params?.result) {
    console.log('Head number', parseInt(msg.params.result.number, 16));
  }
});

Rust (jsonrpsee)

use futures::StreamExt;
use jsonrpsee::ws_client::WsClientBuilder;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = WsClientBuilder::default()
        .build("wss://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY")
        .await?;

    let mut sub = client
        .subscribe::<serde_json::Value>("chain_subscribeNewHeads", None, "chain_unsubscribeNewHeads")
        .await?;

    while let Some(header) = sub.next().await {
        println!("New head: {:?}", header?);
    }

    Ok(())
}

Operational Tips

• Always unsubscribe (chain_unsubscribeNewHeads) when shutting down long-lived clients to free server resources.
• Combine emitted hashes with state_getStorage or state_call for near real-time indexing of NFT minting, fuel tank usage, and marketplace events.
• For finalized data streams, prefer chain_subscribeFinalizedHeads to avoid forks.