发送 RPC 请求

Leafage 对外只有一种协议：HTTP 上的 JSON-RPC 2.0。任何能发 HTTP POST 的客户端都可以直接使用，不需要 SDK。本页从第一个请求开始，逐步覆盖批量调用、区块上下文、gas 估算、模拟与追踪。

端点

场景	端点	说明
生产	`POST http://proxy:8663/{chainId}`	经 nodex-proxy 路由到合适的查询节点，链由路径指定
开发 / 调试	`POST http://127.0.0.1:8659`	直连单个 leafage-evm，没有路由和兜底

chainId 用十进制，ETH 主网是 /1。十六进制写法会被 proxy 规范化为十进制。下文示例以生产端点为准，直连时去掉路径即可。

请求头

头	必需	作用
`Content-Type: application/json`	是	JSON-RPC 请求体
`client-id`	建议	用量上报的聚合键，缺失记为 `unknown`
`x-dbk-biz`、`x-dbk-source`、`x-dbk-source-host`、`x-dbk-env`	否	来源标识，进入 proxy 的日志与 trace
`x-nodex-node-type: archive`	否	强制路由到 Archive 节点池

第一个请求：`eth_call`

读取 USDT 合约的 totalSupply()，函数选择器是 0x18160ddd：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -H 'client-id: my-service' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_call",
    "params": [
      { "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "data": "0x18160ddd" },
      "latest"
    ]
  }'

import requests

RPC_URL = "http://proxy:8663/1"


def rpc(method, params):
    resp = requests.post(
        RPC_URL,
        json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params},
        headers={"client-id": "my-service"},
        timeout=10,
    )
    resp.raise_for_status()
    body = resp.json()
    if "error" in body:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return body["result"]


total_supply = rpc(
    "eth_call",
    [{"to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "data": "0x18160ddd"}, "latest"],
)
print(int(total_supply, 16))

const RPC_URL = "http://proxy:8663/1";

async function rpc(method, params) {
  const res = await fetch(RPC_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json", "client-id": "my-service" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
  });
  const body = await res.json();
  if (body.error) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }
  return body.result;
}

const totalSupply = await rpc("eth_call", [
  { to: "0xdAC17F958D2ee523a2206206994597C13D831ec7", data: "0x18160ddd" },
  "latest",
]);
console.log(BigInt(totalSupply));

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

const rpcURL = "http://proxy:8663/1"

type rpcResponse struct {
	Result json.RawMessage `json:"result"`
	Error  *struct {
		Code    int    `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func call(method string, params ...any) (json.RawMessage, error) {
	payload, err := json.Marshal(map[string]any{
		"jsonrpc": "2.0", "id": 1, "method": method, "params": params,
	})
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequest(http.MethodPost, rpcURL, bytes.NewReader(payload))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("client-id", "my-service")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var body rpcResponse
	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
		return nil, err
	}
	if body.Error != nil {
		return nil, fmt.Errorf("rpc error %d: %s", body.Error.Code, body.Error.Message)
	}
	return body.Result, nil
}

func main() {
	result, err := call("eth_call", map[string]string{
		"to":   "0xdAC17F958D2ee523a2206206994597C13D831ec7",
		"data": "0x18160ddd",
	}, "latest")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(result))
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x00000000000000000000000000000000000000000000000000012a0ff6a2ff40"
}

eth_call 的参数依次是调用对象、区块参数、可选的 stateOverride 和 blockOverrides。调用对象的字段与以太坊的 eth_call 相同：from、to、data / input、value、gas、gasPrice 等。

eth_* 方法与标准以太坊兼容，ethers、viem、web3.py 这类库把 http://proxy:8663/1 当作普通 RPC 端点即可使用。DeBank 命名空间的方法用它们的原始调用接口发送，例如 ethers 的 provider.send(method, params)。

批量请求

请求体是数组时按 JSON-RPC 批量处理，一次往返返回多个结果：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -d '[
    { "jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": [] },
    { "jsonrpc": "2.0", "id": 2, "method": "eth_chainId", "params": [] },
    { "jsonrpc": "2.0", "id": 3, "method": "eth_getBalance",
      "params": ["0xdAC17F958D2ee523a2206206994597C13D831ec7", "latest"] }
  ]'

批量请求作为一个整体被路由到同一个节点。要在一个区块上批量执行合约调用，用下面的 contractMultiCall 比批量 eth_call 更合适：它保证所有调用看到同一份状态。

指定区块：`blockCtx`

DeBank 命名空间的方法名没有前缀，用 blockCtx 对象声明区块上下文。读取某个历史高度的余额：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getAddressBalance",
    "params": [
      "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      { "block_id": "0x1406f40", "type": "Equals" }
    ]
  }'

`type`	含义	路由
`Equals`	精确使用 `block_id` 的状态	距链头 64 块内走 State 节点，更早走 Archive 节点
`Contains`	任何不早于 `block_id` 的状态都可以	始终走 State 节点，在 `latest` 上执行

省略 blockCtx 等同于 latest。语义详见区块上下文与路由。

一次调用多个合约：`contractMultiCall`

在同一份状态上执行一组只读调用，返回每个调用的结果和这份状态对应的区块：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "contractMultiCall",
    "params": [
      [
        { "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "data": "0x18160ddd" },
        { "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "data": "0x18160ddd" }
      ],
      { "block_id": "latest", "type": "Contains" }
    ]
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      { "code": 0, "err": "", "from_cache": false, "result": "0x…", "gas_used": 23675, "time_cost": 0.31 },
      { "code": 0, "err": "", "from_cache": false, "result": "0x…", "gas_used": 30411, "time_cost": 0.28 }
    ],
    "stats": {
      "block_num": 21000000,
      "block_hash": "0x…",
      "block_time": 1735689600,
      "success": true,
      "cache_enabled": false
    }
  }
}

参数顺序是 requests、blockCtx、blockOverrides、stateOverride、fastFail、useParallel、disableCache。可选参数按位置传入，跳过的位置用 null 占位。

可选参数	作用
`fastFail`	某个调用失败后不再执行后续调用
`useParallel`、`disableCache`	当前实现接受但不生效

单个调用的 code 为 0 表示成功；revert 时为 -39000，err 里是解码后的 revert 原因。整个请求只在参数或区块解析失败时才返回 JSON-RPC 级别的错误。

eth_multiCall 是同一能力的 eth 命名空间版本：区块参数用标准写法，响应字段是驼峰（fromCache、gasUsed、blockNum），单个调用的 revert 码是 -40014。两者不要共用同一套解析代码。

估算 gas：`estimateGas`

方法名没有 eth_ 前缀。估算一笔 USDT 转账：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "estimateGas",
    "params": [
      {
        "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
        "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c80000000000000000000000000000000000000000000000000000000005f5e100"
      }
    ]
  }'

返回十六进制的 gas 用量。第二个参数是可选的 blockCtx，第三个是可选的 blockOverrides。

模拟交易序列：`simulateTransactions`

按顺序执行一组交易，后一笔看到前一笔的状态变更，返回每笔的调用追踪与事件：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "simulateTransactions",
    "params": [
      [
        {
          "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
          "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
          "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c80000000000000000000000000000000000000000000000000000000005f5e100"
        }
      ],
      { "block_id": "latest", "type": "Equals" }
    ]
  }'

响应的 results[i] 包含 traces、events、code、err、gas_used；stats 给出模拟所基于的区块。

追踪一次调用：`pre_traceCall`

返回逐指令的 struct log，不需要写节点的 debug API：

curl -s -X POST http://proxy:8663/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "pre_traceCall",
    "params": [
      { "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "data": "0x18160ddd" },
      "latest"
    ]
  }'

第二个参数是可选的区块参数，写法与 eth_call 相同。批量版本是 pre_traceMany。

处理错误

JSON-RPC 级别的错误出现在响应的 error 字段：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -39006, "message": "block … not found for state node" }
}

错误码	含义	客户端应对
`-39000`	执行 revert	业务错误，`message` 含 revert 原因
`-39001` ~ `-39004`	gas 耗尽、余额不足、nonce 错误、EVM 执行失败	业务错误，检查调用参数
`-39006`	State 节点没有该高度	经 proxy 时已自动转 Archive；直连时改发 Archive 节点
`-39007`	区块标识非法	检查高度是否超过链头、哈希是否在规范链上
`-39008`	触及不支持的预编译	经 proxy 时已自动转 Native；直连时改发原链节点
`-41002`	执行超时	缩小调用规模或拆分批量请求
`-32601` / `-32602`	方法不存在 / 参数错误	核对方法名（`estimateGas` 无前缀）与参数顺序

完整错误码表见 RPC 参考。

下一步

RPC 参考

全部方法、参数与返回结构。

区块上下文与路由

Equals / Contains 的语义与 proxy 的路由规则。

开始使用

核心概念

架构

组件

指南

参考

端点

请求头

第一个请求：`eth_call`

批量请求

指定区块：`blockCtx`

一次调用多个合约：`contractMultiCall`

估算 gas：`estimateGas`

模拟交易序列：`simulateTransactions`

追踪一次调用：`pre_traceCall`

处理错误

下一步

RPC 参考

区块上下文与路由

​端点

​请求头

​第一个请求：eth_call

​批量请求

​指定区块：blockCtx

​一次调用多个合约：contractMultiCall

​估算 gas：estimateGas

​模拟交易序列：simulateTransactions

​追踪一次调用：pre_traceCall

​处理错误

​下一步

RPC 参考

区块上下文与路由

端点

请求头

第一个请求：`eth_call`

批量请求

指定区块：`blockCtx`

一次调用多个合约：`contractMultiCall`

估算 gas：`estimateGas`

模拟交易序列：`simulateTransactions`

追踪一次调用：`pre_traceCall`

处理错误

下一步