JSON-RPC

所有链与网络都提供基于 HTTP POST 的 JSON-RPC 入口。请从控制台复制目标 Gateway 的 Access Point。

请求格式

Gateway 接受单个严格的 JSON-RPC 2.0 对象：


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

约束如下：

jsonrpc 必须是字符串 "2.0"；
method 必须是非空字符串；
params 如果出现，只能是数组或对象；
id 如果出现，只能是字符串、整数或 null；
顶层数组形式的 batch 请求不支持。

推荐发送 Content-Type: application/json。请求正文超出部署限制时返回 HTTP 413，正文读取超时时返回 HTTP 408。

请求执行顺序

Gateway 完成鉴权和限流后，会先判断请求是否符合免 Endpoint 调用策略并查询 Accelerator：

缓存命中时直接返回共享结果；
缓存未命中且 route 有可用 Endpoint 时，转发给选中的 Endpoint；
缓存未命中且没有 Endpoint 时，返回 -32004 No available Endpoint。

不符合 Accelerator 策略的方法会直接进入 route。完整 RPC Method Catalog 不等于免 Endpoint 方法列表。

不同协议示例

先设置不含 Path Key 的 Access Point 和 App Key：


export RPC_URL='<access_point_without_path_key>'
export APP_API_KEY='<app_api_key>'

EVM：


curl "$RPC_URL" -H "Authorization: Bearer $APP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Solana：


curl "$RPC_URL" -H "Authorization: Bearer $APP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[{"commitment":"finalized"}]}'

Bitcoin 或 Litecoin：


curl "$RPC_URL" -H "Authorization: Bearer $APP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo","params":[]}'

TRON JSON-RPC：


curl "$RPC_URL" -H "Authorization: Bearer $APP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Accelerator 未命中后，Gateway 会把方法转发给 route 选中的 Endpoint。上游返回的有效 JSON-RPC application error 是最终结果，不会因为业务错误自动切换到另一个 Endpoint。

Notification

省略 id 表示 notification：


{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x..."]}

Gateway 对 notification 返回 HTTP 204，没有响应正文。客户端无法从 notification 判断上游是否最终接受请求。

Notification 也无法判断 Accelerator 是否命中，因此不要把它用于免 Endpoint 调用。

响应处理

普通调用的成功和 JSON-RPC 错误通常都使用 HTTP 200。客户端必须检查 result 或 error：


{"jsonrpc":"2.0","id":1,"error":{"code":-32004,"message":"No available Endpoint.","data":{"type":"gateway_error"}}}

完整网关错误码见错误与排查。

当前不支持

JSON-RPC batch；
WebSocket 订阅和 ws://、wss:// Endpoint；
公开 gRPC；
由 Gateway 补齐上游没有实现的方法或历史数据。