链上 API 参考

三块内容按「离节点由近到远」排列：最底层是节点自己的 JSON-RPC 接口，中间是封装它的函数库，最上层是浏览器钱包与签名标准。排查问题时从上往下找：界面不对 → 函数库调用 → 最终打印出来的 RPC 请求体。

所有 EVM 节点都实现这套接口。dApp 用的 ethers / viem 只是它的上层封装，出问题时最终都要回到这里排查——把请求体打印出来，就知道到底发的是什么。数值全部用十六进制字符串（0x 前缀），大整数不要在前端转成 Number。

eth_chainId网络信息返回当前链的 chainId（十六进制）。前端切换网络后必须先核对它，再发交易。▾

返回当前链的 chainId（十六进制）。前端切换网络后必须先核对它，再发交易。

返回：QUANTITY - 十六进制 chainId，例如 0x1 表示以太坊主网

请求示例JSON

// 请求
{ "jsonrpc": "2.0", "id": 1, "method": "eth_chainId", "params": [] }

// 响应
{ "jsonrpc": "2.0", "id": 1, "result": "0x1" }

0x1 以太坊主网、0xa 后者为 Optimism(10)、0x2105 为 Base(8453)、0xa4b1 为 Arbitrum One(42161)。

eth_blockNumber网络信息返回最新区块高度。常用于判断节点是否同步、以及做基础的存活探测。▾

返回最新区块高度。常用于判断节点是否同步、以及做基础的存活探测。

返回：QUANTITY - 十六进制区块高度

请求示例JSON

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

// -> { "result": "0x14e5a3c" }  = 21879356

eth_syncing网络信息节点是否处于同步中。返回 false 表示已同步，返回对象时字段是同步进度。▾

节点是否处于同步中。返回 false 表示已同步，返回对象时字段是同步进度。

返回：boolean | object

请求示例JSON

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

// -> false（已同步）
// -> { "currentBlock": "0x1", "highestBlock": "0x14e5a3c", ... }（同步中）

自建节点做生产 RPC 时，同步未完成就对外提供服务会返回过期数据。

eth_getBalance账户与余额查询地址的原生币余额（ETH / BNB / MATIC 等）。▾

查询地址的原生币余额（ETH / BNB / MATIC 等）。

参数（按顺序）

名称	类型	说明
address	DATA, 20 Bytes	要查询的地址
block	string \| object	latest / earliest / pending / safe / finalized，或十六进制区块号、32 字节区块哈希

返回：QUANTITY - wei 为单位的十六进制余额

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBalance",
  "params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest"]
}

// -> { "result": "0x1bc16d674ec80000" }  = 2 ETH

代币余额（ERC-20）不是这个接口，要 eth_call 调 balanceOf。

eth_getTransactionCount账户与余额返回地址已发送的交易数，也就是下一笔交易的 nonce。▾

返回地址已发送的交易数，也就是下一笔交易的 nonce。

参数（按顺序）

名称	类型	说明
address	DATA, 20 Bytes	账户地址
block	string \| object	latest / earliest / pending / safe / finalized，或十六进制区块号、32 字节区块哈希

返回：QUANTITY - 下一个可用 nonce

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionCount",
  "params": ["0x...", "pending"]
}

// -> { "result": "0x2a" }  = 42

用 pending 才能拿到包含待打包交易的 nonce；用 latest 会在连续发交易时造成 nonce 冲突。

eth_getCode账户与余额返回地址上的字节码。用来判断一个地址是合约还是普通账户（EOA）。▾

返回地址上的字节码。用来判断一个地址是合约还是普通账户（EOA）。

参数（按顺序）

名称	类型	说明
address	DATA, 20 Bytes	待检测地址
block	string \| object	latest / earliest / pending / safe / finalized，或十六进制区块号、32 字节区块哈希

返回：DATA - 字节码，普通账户返回 0x

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getCode",
  "params": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "latest"]
}

// -> { "result": "0x6080604052..." }  （USDC 合约）
// 普通账户 -> { "result": "0x" }

转账前用它确认目标确实是合约，能挡掉一部分「转到钓鱼 EOA」的骗局。

eth_call读取合约在不产生交易、不花 Gas 的前提下执行合约的只读函数。所有 view / pure 函数都靠它。▾

在不产生交易、不花 Gas 的前提下执行合约的只读函数。所有 view / pure 函数都靠它。

参数（按顺序）

名称	类型	说明
tx	object	{ from?, to, gas?, gasPrice?, value?, data } — data 是 4 字节选择器 + ABI 编码参数
block	string \| object	latest / earliest / pending / safe / finalized，或十六进制区块号、32 字节区块哈希

返回：DATA - ABI 编码的返回值

请求示例JSON

// 调用 USDC 的 balanceOf(0xd8dA...6045)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_call",
  "params": [
    {
      "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "data": "0x70a08231000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045"
    },
    "latest"
  ]
}

// -> { "result": "0x0000000000000000000000000000000000000000000000000000000011e1a300" }

0x70a08231 就是 balanceOf(address) 的函数选择器。手动拼 calldata 是排查 ABI 问题的必备技能。

eth_estimateGasGas 与费用估算一笔交易需要多少 gas。写入接口前必须调用，否则很容易 out of gas。▾

估算一笔交易需要多少 gas。写入接口前必须调用，否则很容易 out of gas。

参数（按顺序）

名称	类型	说明
tx	object	{ from, to?, value?, data? }
block	string	可选，默认 latest；多数节点也接受 pending

返回：QUANTITY - 估算出的 gas 上限

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_estimateGas",
  "params": [{
    "from": "0x...",
    "to": "0xA0b8...eB48",
    "data": "0xa9059cbb000000000000000000000000..."
  }]
}

// -> { "result": "0xc2f8" }  = 49912

估算值会随链上状态变化，实际发送时建议乘 1.1–1.3 倍留出余量；估算失败通常意味着交易本身会 revert。

eth_gasPriceGas 与费用返回节点建议的 gas 单价（EIP-1559 之前的旧接口，兼容性最好）。▾

返回节点建议的 gas 单价（EIP-1559 之前的旧接口，兼容性最好）。

返回：QUANTITY - wei 为单位的 gas 单价

请求示例JSON

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

// -> { "result": "0x6fc23ac00" }  = 30 gwei

eth_maxPriorityFeePerGasGas 与费用EIP-1559 下的建议小费（优先费），与 baseFee 一起决定实际 gas 价格。▾

EIP-1559 下的建议小费（优先费），与 baseFee 一起决定实际 gas 价格。

返回：QUANTITY - wei 为单位的小费

请求示例JSON

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

// -> { "result": "0x5d21dba00" } = 25 gwei

实际要付的 maxFeePerGas ≈ baseFee * 2 + 小费，设置过低会在网络拥堵时长期挂起。

eth_feeHistoryGas 与费用返回最近若干区块的基础费与优先费历史，是钱包做动态费率推荐的标准数据源。▾

返回最近若干区块的基础费与优先费历史，是钱包做动态费率推荐的标准数据源。

参数（按顺序）

名称	类型	说明
blockCount	QUANTITY	要查询的区块数，建议 4–20
newestBlock	string	最新区块号或 latest
rewardPercentiles	number[]	要统计的百分位，例如 [25, 50, 75]

返回：object - { baseFeePerGas[], gasUsedRatio[], reward[][] }

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_feeHistory",
  "params": ["0x5", "latest", [25, 50, 75]]
}

// -> {
//   "oldestBlock": "0x14e5a30",
//   "baseFeePerGas": ["0x3d4a1a2c0", "0x3c9f1c8c0", ...],
//   "gasUsedRatio": [0.52, 0.71, 0.43, 0.88, 0.61],
//   "reward": [["0x59682f00", "0x59682f00", "0x77359400"], ...]
// }

eth_sendRawTransaction发送交易广播一笔已签名的交易。这是唯一能真正改变链上状态的入口之一。▾

广播一笔已签名的交易。这是唯一能真正改变链上状态的入口之一。

参数（按顺序）

名称	类型	说明
signedTxData	DATA	RLP 编码并签名后的完整交易字节流

返回：DATA, 32 Bytes - 交易哈希

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendRawTransaction",
  "params": ["0x02f8700182031184773594008504a817c80082520894d8da..."]
}

// -> { "result": "0x33469b22e9f636356c4160a87eb19df52b7412e8eac32a4a55ffe88ea8350788" }

哈希只代表「已接收」，不代表成功。必须再轮询 eth_getTransactionReceipt 看 status 才是真的成功。

eth_getTransactionReceipt发送交易根据交易哈希拿回执，包含执行状态、gas 消耗、日志与合约地址。▾

根据交易哈希拿回执，包含执行状态、gas 消耗、日志与合约地址。

参数（按顺序）

名称	类型	说明
txHash	DATA, 32 Bytes	交易哈希

返回：object | null - 未打包时返回 null

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionReceipt",
  "params": ["0x33469b22...0788"]
}

// -> {
//   "status": "0x1",                 // 0x1 成功，0x0 失败
//   "blockNumber": "0x14e5a3c",
//   "gasUsed": "0xc2f8",
//   "effectiveGasPrice": "0x3f5476a00",
//   "contractAddress": null,
//   "logs": [ ... ]
// }

失败交易（status 0x0）同样消耗 gas 并已上链，会拿到全额的 gasUsed 扣款。

eth_getTransactionByHash发送交易查询交易详情。常用于展示「这笔交易到底发没发出去」。▾

查询交易详情。常用于展示「这笔交易到底发没发出去」。

参数（按顺序）

名称	类型	说明
txHash	DATA, 32 Bytes	交易哈希

返回：object | null

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionByHash",
  "params": ["0x33469b22...0788"]
}

// -> { "nonce": "0x2a", "to": "0x...", "value": "0x0", "input": "0xa9059cbb...", ... }

eth_getLogs日志与事件按地址与 topic 过滤事件日志，是索引器、看板、空投快照的核心接口。▾

按地址与 topic 过滤事件日志，是索引器、看板、空投快照的核心接口。

参数（按顺序）

名称	类型	说明
filter	object	{ fromBlock, toBlock, address?, topics?, blockHash? }

返回：array - 日志对象数组 { address, topics, data, blockNumber, transactionHash, logIndex }

请求示例JSON

// 拉取某 ERC-20 合约最近 1000 个区块的 Transfer 事件
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getLogs",
  "params": [{
    "fromBlock": "0x14e0000",
    "toBlock": "latest",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      null,
      "0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045"
    ]
  }]
}

topics[0] 是事件签名哈希，后面按事件定义中 indexed 参数的顺序填；null 表示该位不过滤。区间过大会被节点拒绝，需要分页拉取。

eth_subscribe日志与事件WebSocket 订阅新块、日志或待打包交易，用于实时监控。▾

WebSocket 订阅新块、日志或待打包交易，用于实时监控。

参数（按顺序）

名称	类型	说明
subscription	string	newHeads / logs / newPendingTransactions / syncing
filter	object	仅 logs 需要，格式同 eth_getLogs 的 filter

返回：string - 订阅 ID，后续事件通过 eth_subscription 通知推送

请求示例JSON

// 订阅新块（需 WebSocket 连接，不能走 HTTP）
{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }

// -> { "result": "0x9cef478923ff08bf67fde6c64013158d" }

// 之后服务端推：
// { "method": "eth_subscription",
//   "params": { "subscription": "0x9cef...", "result": { "number": "0x14e5a3d", ... } } }

订阅会在断线时静默失效，生产环境必须实现重连 + 断点补拉（用 eth_getLogs 补齐缺口）。

eth_getBlockByNumber网络信息按区块号取区块头与交易列表，用于算确认数、算时间间隔。▾

按区块号取区块头与交易列表，用于算确认数、算时间间隔。

参数（按顺序）

名称	类型	说明
block	QUANTITY \| string	区块号或 latest / finalized
fullTx	boolean	true 返回完整交易对象，false 只返回哈希数组

返回：object | null

请求示例JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBlockByNumber",
  "params": ["latest", false]
}

// -> { "number": "0x14e5a3c", "timestamp": "0x671a8f21", "baseFeePerGas": "0x3d4a1a2c0", ... }

确认数 = 当前区块号 - 交易所在区块号 + 1。交易所通常要求 12 确认（以太坊）或按 L2 的软确认规则。