traceBlocks

traceBlocks is a real-time stream of logs and state diffs, delivered as soon as each BSC block is executed.

Stream Endpoint

• Method: traceBlocks

• Endpoint: ws://traceblocks-bsc.rpc.blxrbdn.com:50055/ws

Every connection needs the access token we share with you. A missing or incorrect token is rejected when you connect.

Options

Key	Description	Values
include	Fields to include in the block stream.	logs, state_diffs, or both. Default: logs. Unrecognized values are rejected.
logs	Filter by contract address and event topic.	Object with optional addresses and topics lists.
state_diffs	Filter by contract and storage slot.	Object with optional contracts and slots lists.
blockchain_network	Network to subscribe to.	BSC-Mainnet

Filtering by logs

addresses and topics are both optional. An empty or omitted list leaves that dimension unconstrained. When both are set, a log must match both.

Topics match in any position, not positionally as in eth_getLogs. You don't need to know whether your topic is in topic0 or an indexed argument.

A matching transaction includes only the logs that matched, not every log it emitted.

{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["traceBlocks",{
  "include":["logs"],
  "blockchain_network":"BSC-Mainnet",
  "logs":{
    "addresses":["0x0eD7e52944161450477ee417DE9Cd3a859b14fD0"],
    "topics":["0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822"]
  }
}]}

Filtering by state diffs

contracts and slots follow the same rule as the logs filter.

A matching transaction includes its entire state diff across every contract it touched, not just the matching slot.

{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["traceBlocks",{
  "include":["state_diffs"],
  "blockchain_network":"BSC-Mainnet",
  "state_diffs":{
    "contracts":["0x0eD7e52944161450477ee417DE9Cd3a859b14fD0"],
    "slots":["0x0000000000000000000000000000000000000000000000000000000000000008"]
  }
}]}

Combining filters

Set include to both logs and state_diffs and provide both filters to receive any transaction that matches either one. Within a filter the conditions are ANDed; between the two filters it's OR.

A transaction matched only through its state diff carries no logs. If neither filter is set, every transaction in every block is sent.

Examples (Websocket)

wscat -c ws://traceblocks-bsc.rpc.blxrbdn.com:50055/ws --header "Authorization: <ACCESS-TOKEN>"
> {"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["traceBlocks", {"include": ["logs"], "blockchain_network": "BSC-Mainnet"}]}
< {"jsonrpc":"2.0","id":1,"result":"<subscription-id>"}

(Node.js, Python and Golang tabs: keep as they are, but replace the endpoint with <ENDPOINT> and change the params to ["traceBlocks", {"include": ["logs"], "blockchain_network": "BSC-Mainnet"}].)

A failed subscription returns an error object:

{"jsonrpc":"2.0","id":1,"error":{"code":-32002,"message":"..."}}

Response (Block Event)

You receive one notification per block.

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "subscription": "<subscription-id>",
    "result": {
      "hash": "0x<block hash>",
      "header": {"number": "12345678"},
      "transactions": [
        {
          "hash": "0x<tx hash>",
          "logs": [
            {"address": "0x...", "topics": ["0x...", "0x..."], "data": "0x..."}
          ],
          "stateDiff": {
            "0x<contract>": {"slots": {"0x<slot>": "0x<new value>"}}
          }
        }
      ]
    }
  }
}

logs and stateDiff appear on a transaction only if you requested that content and the transaction has it.

transactions is always present. An empty list means nothing in the block matched your filter, not that something is wrong with the stream.