# JSON-RPC

> JSON-RPC request format, examples, response semantics, and limitations.

Canonical page: https://rpc.aurpay.net/docs/json-rpc

Every [chain and network](https://rpc.aurpay.net/docs/chains.md) 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:

```json
{
  "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](https://rpc.aurpay.net/docs/endpoint-free-rpc.md) 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.

[Diagram: Request flow: authentication and rate limiting precede the Endpoint-free RPC policy check; a cache hit returns the shared result, while a miss forwards through the Route to an Endpoint.]

## Protocol examples

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

```bash
export RPC_URL='<access_point_without_api_key>'
export APP_API_KEY='<app_api_key>'
```

EVM:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```json
{"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.

> Use a request with an `id` whenever the client needs confirmation, error details, or cache-result visibility. Reserve Notifications for calls whose completion requires no response.

## 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:

```json
{"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:

```json
{"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](https://rpc.aurpay.net/docs/errors.md) 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

- [Errors and recovery](https://rpc.aurpay.net/docs/errors.md)
- [Endpoint-free RPC](https://rpc.aurpay.net/docs/endpoint-free-rpc.md)
- [Authentication](https://rpc.aurpay.net/docs/authentication.md)