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

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