JSON-RPC

Every chain and network exposes JSON-RPC over HTTP POST. Copy the target Gateway Access Point from the dashboard.

Request format

The Gateway accepts one strict JSON-RPC 2.0 object:

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

Requirements:

• jsonrpc must be the string "2.0";
• method must be a non-empty string;
• params, when present, must be an array or object;
• id, when present, must be a string, integer, or null.

Send Content-Type: application/json, keep the body within the deployed request-size limit, and complete the upload within the configured read window.

Request execution order

After authentication and admission, the Gateway classifies the request against the Endpoint-free RPC policy and checks the shared cache:

1. A cache hit returns the shared result immediately.
2. On a miss, a route with a usable Endpoint forwards to the selected target.

A request outside the Endpoint-free RPC policy continues directly to the Route. Use the complete RPC Method Catalog for Route configuration and the Endpoint-free RPC page for the cached request set.

Protocol examples

Set an Access Point that does not carry the API Key in its path, plus the API Key itself:

export RPC_URL='<access_point_without_api_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 or 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":[]}'

After a cache miss, the Gateway forwards the method to an Endpoint selected by the Route. For an ID-bearing request, a valid upstream JSON-RPC error is returned as the final application response. A success result is accepted only when it arrives with an upstream HTTP 2xx status.

Notifications

Omitting id creates a Notification:

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

An explicit "id": null is an ordinary request, not a Notification, and receives a JSON-RPC Response. For a Notification, the Gateway still applies routing and method-aware failover, but returns HTTP 204 with no response body. The 204 confirms only that no JSON-RPC Response was produced; it does not establish successful routing or forwarding, upstream acceptance or processing, method or transaction success, or network acceptance.

Response handling

Use Response compression to negotiate gzip or zstd for large results. Decode the HTTP response before inspecting the JSON-RPC body.

For an ID-bearing request, regular success responses and JSON-RPC errors normally both use HTTP 200. Inspect result or error in every JSON-RPC Response. A successful call has this shape:

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

The Gateway accepts an upstream result as successful only when the Endpoint also returned HTTP 2xx. A result inside a non-2xx upstream response is treated as an inconsistent Endpoint response: the Gateway applies operation-aware failover when safe, or returns -32005 after the allowed attempts are exhausted. A valid upstream JSON-RPC error remains the final application response regardless of its upstream HTTP status.

Use an ID-bearing request when submitting a transaction:

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

A transaction hash in result acknowledges submission. It does not prove inclusion, confirmation, or finality; track the transaction using the target chain’s confirmation rules.

See Errors and recovery for the complete Gateway error table.

Supported transport

The public Gateway accepts one JSON-RPC 2.0 object per HTTP POST. Method and historical-data coverage follows the configured upstream Endpoint, including its enabled namespaces, plan, and archive depth.

Related