What Is JSON-RPC? A Practical Guide for API Developers

JSON-RPC 2.0 is a lightweight remote procedure call protocol that encodes actions as method names in the request body rather than HTTP verbs and URL paths. Build and validate JSON-RPC payloads with our JSON-RPC Tester.

The Request Structure

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [42, 23],
  "id": 1
}

Four fields: "jsonrpc" must always be "2.0". "method" is the server-side function to invoke. "params" can be an array (positional) or object (named). "id" correlates the response — omit it for notifications where no response is expected.

Requests vs Notifications

A request expects a response. A notification (no "id" field) is fire-and-forget — the server processes it but never replies. Use notifications for events, logging, or pub-sub patterns where acknowledgment is not required.

Batch Requests

Send an array of request objects to invoke multiple methods in a single HTTP round-trip. The server returns an array of responses — one per request, none for notifications. Batch requests dramatically reduce latency for operations that can be parallelised on the server.

Standard Error Codes

JSON-RPC vs REST

REST distributes actions across HTTP verbs (GET, POST, PUT, DELETE) and URL paths. JSON-RPC uses a single endpoint and encodes actions in the body. JSON-RPC is common in Ethereum APIs (eth_getBalance), Language Server Protocol (LSP), and internal RPC transports. REST is better for resource-oriented public APIs where cacheability and HTTP semantics matter.