> For the complete documentation index, see [llms.txt](https://docs.bloxroute.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloxroute.com/bsc/streams/receipts-streams/traceblocks.md). # 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. ```json {"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. ```json {"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)** ```bash wscat -c ws://traceblocks-bsc.rpc.blxrbdn.com:50055/ws --header "Authorization: " > {"jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["traceBlocks", {"include": ["logs"], "blockchain_network": "BSC-Mainnet"}]} < {"jsonrpc":"2.0","id":1,"result":""} ``` *(Node.js, Python and Golang tabs: keep as they are, but replace the endpoint with `` and change the params to `["traceBlocks", {"include": ["logs"], "blockchain_network": "BSC-Mainnet"}]`.)* A failed subscription returns an error object: ```json {"jsonrpc":"2.0","id":1,"error":{"code":-32002,"message":"..."}} ``` **Response (Block Event)** You receive one notification per block. ```json { "jsonrpc": "2.0", "method": "subscribe", "params": { "subscription": "", "result": { "hash": "0x", "header": {"number": "12345678"}, "transactions": [ { "hash": "0x", "logs": [ {"address": "0x...", "topics": ["0x...", "0x..."], "data": "0x..."} ], "stateDiff": { "0x": {"slots": {"0x": "0x"}} } } ] } } } ``` `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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bloxroute.com/bsc/streams/receipts-streams/traceblocks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.