---
updatedAt: 2026-09-08T09:54:11.000Z
agentTools:
  projectIndex: https://cn.developers.tron.network/llms.txt
---

# GetBlockByNum

按高度查询区块——SolidityNode 版本可用作"该区块是否已固化"的探测器（拿到 = 已固化）。

> 📘 **用作固化探测器**
>
> 在 SolidityNode 上，**能查到 = 已固化；查不到 = 尚未固化**。这是判断一笔交易是否进入终态的常用模式——拿到该交易的区块号后，调本接口探测；返回成功即可视为终态确认。

***

## 确认语义

接口成功返回区块对象时，表示该 block number 已在 SolidityNode 视图中固化。如果按某个高度查询不到区块，通常表示该高度尚未固化、SolidityNode 尚未同步到该高度，或请求的高度不存在。扫描程序应等待下一轮轮询，而不是把它记录为业务失败。

按高度扫描已固化区块时，应持久化已完成处理的最高 block number。交易本体、receipt、Event 和内部交易的解析分工，参见[基于区块扫描的充值监听机制](doc:exchangewallet-integrate-with-the-tron-network#5-基于区块扫描的充值监听机制)。

***

## 相关资源

* [GetBlockByNum (FullNode)](https://cn.developers.tron.network/reference/wallet-getblockbynum) —— FullNode 版本（含未固化）
* [GetBlock](https://cn.developers.tron.network/reference/getblock-2) —— 同时支持按高度或按 ID 查询
* [GetNowBlock](https://cn.developers.tron.network/reference/getnowblock) —— 查询最新已固化区块（链头探测的反向）
* [区块](https://cn.developers.tron.network/docs/block) —— 区块结构、复合区块 ID 和区块查询接口选型
* [基于区块扫描的充值监听机制](doc:exchangewallet-integrate-with-the-tron-network#5-基于区块扫描的充值监听机制) —— 已固化区块扫描和交易解析流程

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "全节点 HTTP API",
    "version": "4.8.0"
  },
  "servers": [
    {
      "url": "https://api.shasta.trongrid.io",
      "description": "Shasta 测试网"
    },
    {
      "url": "https://nile.trongrid.io",
      "description": "Nile 测试网"
    },
    {
      "url": "https://api.trongrid.io",
      "description": "TRON 主网（真实资产）"
    }
  ],
  "components": {
    "schemas": {
      "NodeHttpBusinessError": {
        "title": "错误信息",
        "type": "object",
        "description": "请求处理发生异常时，java-tron 可能随 HTTP 200 返回此格式；具体错误信息位于 `Error` 字段。",
        "required": [
          "Error"
        ],
        "properties": {
          "Error": {
            "type": "string",
            "description": "java-tron 返回的错误信息。"
          }
        },
        "examples": [
          {
            "Error": "Invalid request parameters."
          }
        ],
        "additionalProperties": false
      }
    }
  },
  "security": [
    {}
  ],
  "paths": {
    "/walletsolidity/getblockbynum": {
      "post": {
        "summary": "GetBlockByNum",
        "description": "查询指定区块是否已固化。若能获取到区块，则表明该区块已固化；若无法获取，则表明尚未固化。",
        "operationId": "getblockbynum",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "num": {
                    "type": "integer",
                    "format": "int32",
                    "description": "区块编号（高度）。示例：`61815425`"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求正常完成时，响应体为接口返回结果；请求处理发生异常时，HTTP 状态仍可能为 200，此时仅返回包含 `Error` 字段的错误信息。",
            "content": {
              "application/json": {
                "examples": {
                  "Example API Call Output": {
                    "value": {
                      "blockID": "00000000000000c82a54a3bbdc956e1ddebc903f29b8daf28505b56f55a3f87d",
                      "block_header": {
                        "raw_data": {
                          "number": 200,
                          "txTrieRoot": "0000000000000000000000000000000000000000000000000000000000000000",
                          "witness_address": "411661f25387370c9cd3a9a5d97e60ca90f4844e7e",
                          "parentHash": "00000000000000c7c8f27726916dfddca3c1c3481eb01da8a08938263674cea4",
                          "timestamp": 1529892138000
                        },
                        "witness_signature": "691e9116963b54ef7eb07692266319b029217e4d4ae8e8cb97e341617460f3822eff149c690aac6f2e0ad27d0af4fa8824d113d7a71c091245f778438ca4bde801"
                      }
                    }
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "title": "返回结果",
                      "not": {
                        "type": "object",
                        "required": [
                          "Error"
                        ]
                      },
                      "type": "object",
                      "properties": {
                        "blockID": {
                          "type": "string",
                          "example": "00000000000000c82a54a3bbdc956e1ddebc903f29b8daf28505b56f55a3f87d"
                        },
                        "block_header": {
                          "type": "object",
                          "properties": {
                            "raw_data": {
                              "type": "object",
                              "properties": {
                                "number": {
                                  "type": "integer",
                                  "example": 200,
                                  "default": 0
                                },
                                "txTrieRoot": {
                                  "type": "string",
                                  "example": "0000000000000000000000000000000000000000000000000000000000000000"
                                },
                                "witness_address": {
                                  "type": "string",
                                  "example": "411661f25387370c9cd3a9a5d97e60ca90f4844e7e"
                                },
                                "parentHash": {
                                  "type": "string",
                                  "example": "00000000000000c7c8f27726916dfddca3c1c3481eb01da8a08938263674cea4"
                                },
                                "timestamp": {
                                  "type": "integer",
                                  "example": 1529892138000,
                                  "default": 0
                                }
                              }
                            },
                            "witness_signature": {
                              "type": "string",
                              "example": "691e9116963b54ef7eb07692266319b029217e4d4ae8e8cb97e341617460f3822eff149c690aac6f2e0ad27d0af4fa8824d113d7a71c091245f778438ca4bde801"
                            }
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/NodeHttpBusinessError"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```