# JSON-RPC

**JSON-RPC** is a stateless, lightweight remote procedure call (RPC) protocol that uses JSON as its data format. The specification defines several data structures and the rules for processing them, and it is transport agnostic: the same concepts work within a single process, over sockets, over HTTP, or in other message-passing environments.<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup> The current version, JSON-RPC 2.0, is maintained by the JSON-RPC Working Group.<sup>[2](https://www.json-rpc.org/specification)</sup>

| Key fact | Detail |
|---|---|
| What it is | A stateless, lightweight RPC protocol using JSON (RFC 4627) as the data format, transport agnostic across processes, sockets, HTTP, and other message-passing environments<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup> |
| Current version | JSON-RPC 2.0, origin date 2010-03-26 (based on the 2009-05-24 version), updated 2013-01-04<sup>[2](https://www.json-rpc.org/specification)</sup> |
| Core objects | Request objects (with `method`, `params`, optional `id`), Response objects (with `result` or `error`), and Notifications, which are requests without an `id` that the server must not answer<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup> |
| Parameters | By-position as an Array or by-name as an Object, with names matching the server's expected parameters exactly, including case<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup> |
| Reserved errors | Codes from -32768 to -32000 are reserved for pre-defined errors such as -32700 Parse error, -32601 Method not found, and -32602 Invalid params<sup>[2](https://www.json-rpc.org/specification)</sup> |
| Batch calls | A client may send an Array of Request objects; the server responds with an Array of Response objects, which may arrive in any order and are matched by `id`<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup> |
| Major deployments | Every Ethereum client implements a JSON-RPC specification, and the Model Context Protocol (MCP) uses JSON-RPC 2.0 as its message format<sup>[3](https://ethereum.org/developers/docs/apis/json-rpc/)</sup><sup> • </sup><sup>[4](https://paymentauth.org/draft-payment-transport-mcp-00.pdf)</sup>  |

## History

The protocol began with a conversation on an SVG IRC channel on March 12, 2004. Jim Ley suggested looking at JSON as a simple encoding scheme for client/server communication; the account's author, a fan of [XML-RPC](https://www.edgepedia.org/xml-rpc), implemented a JSON module in [JavaScript](https://www.edgepedia.org/javascript) that evening, and Robin Berjon remarked that "someone should define JSON-RPC", which was done the same evening.<sup>[5](https://www.jsonrpc.org/archive_json-rpc.org/about.html)</sup> Additional specifications and changes were proposed by members of the mailing list from 2004 onward.<sup>[5](https://www.jsonrpc.org/archive_json-rpc.org/about.html)</sup>

**Version 1.1** was published as a working draft on 7 August 2006, edited by Atif Aziz and Jan-Klaas Kollhof. Unlike the transport-agnostic 2.0, JSON-RPC 1.1 was bound to HTTP only, and it renamed the request and response to Procedure Call and Procedure Return.<sup>[6](https://www.jsonrpc.org/historical/json-rpc-1-1-wd.html)</sup> The 1.1 draft also noted that the array form of parameters was the only one supported in JSON-RPC 1.0, so 1.1 servers could continue to accept calls from existing 1.0 clients.<sup>[6](https://www.jsonrpc.org/historical/json-rpc-1-1-wd.html)</sup>

**Version 2.0** carries origin date 2010-03-26, based on a 2009-05-24 version, with an update dated 2013-01-04.<sup>[2](https://www.json-rpc.org/specification)</sup> The 2.0 Request and Response objects do not work with existing JSON-RPC 1.0 clients or servers, and the specification discourages using Null as an `id` value because 2.0 reserves Null for responses with an unknown id while 1.0 used Null for notifications.<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup>

## How the protocol works

A remote method is invoked by sending a request object serialized in JSON. In version 1.0 the request carried three properties: `method`, a string naming the method to invoke; `params`, an array of arguments; and `id`, a value of any type used to match the response to its request.<sup>[7](https://www.jsonrpc.org/archive_json-rpc.org/specification.html)</sup> In 2.0 the request object carries a `jsonrpc` member set to exactly "2.0", and parameters may be structured either by-position through an Array or by-name through an Object.<sup>[2](https://www.json-rpc.org/specification)</sup><sup> • </sup><sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup>

**Responses and errors.** The server must reply with a Response object except for notifications. On success the response contains a `result` member; on error it contains an `error` member, and the two must not both appear. The `id` member must echo the request's id, or be Null if the id could not be detected, for example on a parse error.<sup>[2](https://www.json-rpc.org/specification)</sup> The error object contains an integer `code`, a short `message`, and an optional `data` value with server-defined detail.<sup>[2](https://www.json-rpc.org/specification)</sup>

The reserved error codes are:<sup>[2](https://www.json-rpc.org/specification)</sup>

| Code | Message | Meaning |
|---|---|---|
| -32700 | Parse error | Invalid JSON was received by the server |
| -32600 | Invalid Request | The JSON sent is not a valid Request object |
| -32601 | Method not found | The method does not exist or is not available |
| -32602 | Invalid params | Invalid method parameter(s) |
| -32603 | Internal error | Internal JSON-RPC error |
| -32000 to -32099 | Server error | Reserved for implementation-defined server errors |

**Notifications and batches.** A Notification is a Request object without an `id`; it signals that the client has no interest in a response, and the server must not reply, including within a batch. Because notifications have no response object, the client would not learn of errors such as Invalid params.<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup> For batch calls, the client may send an Array of Request objects and the server responds with an Array of corresponding Response objects after processing; responses may be returned in any order, and the client matches them to requests by `id`. A server may process a batch as concurrent tasks with any width of parallelism. If the batch itself is not valid JSON or not an array with at least one value, the server must return a single Response object, and it must not return an empty array.<sup>[1](https://www.jsonrpc.org/specification?from=20423&from_column=20423)</sup>

## Scope and design choices

JSON-RPC 2.0 deliberately leaves out features found in larger RPC frameworks. The [OpenDaylight](https://www.edgepedia.org/opendaylight) project's developer guide notes that the specification is not an enterprise bus specification and leaves discovery, naming, and similar concerns out of scope, leaving them to implementers.<sup>[8](https://docs.opendaylight.org/projects/jsonrpc/en/latest/dev-guide.html)</sup> [The 1](https://www.edgepedia.org/the-1).1 draft likewise stated that JSON-RPC does not address security, correlation, reliability, session management, or state management, encouraging developers to use features of HTTP and related Internet technologies instead.<sup>[6](https://www.jsonrpc.org/historical/json-rpc-1-1-wd.html)</sup> An IETF draft on YANG-modeled JSON-RPC also observed shortcomings in the 2.0 specification, including the absence of means for describing and documenting an API, which motivated its own modeling approach.<sup>[9](https://datatracker.ietf.org/doc/html/draft-yang-json-rpc)</sup>

Because the protocol is transport agnostic, implementations exist for HTTP, ZeroMQ, and other transports; OpenDaylight's implementation provides full support for the ZeroMQ transport.<sup>[8](https://docs.opendaylight.org/projects/jsonrpc/en/latest/dev-guide.html)</sup> When run over HTTP(S), the request is simply posted as the message body, allowing JSON-RPC to run over HTTPS and inherit its security attributes.<sup>[10](https://ww1.microchip.com/downloads/en/Appnotes/ENT-AN1126-4.3_VPPD-04260.pdf)</sup>

## Interface description with OpenRPC

The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs, allowing humans and computers to discover and understand a service's capabilities without access to source code, additional documentation, or network traffic inspection. It is exclusively for APIs adhering to the JSON-RPC 2.0 spec and does not cover REST APIs.<sup>[11](https://spec.open-rpc.org/)</sup> Machine-readable definition documents support interactive documentation, code generation for documentation, clients, servers, and automation of test cases.<sup>[11](https://spec.open-rpc.org/)</sup> A JSON-RPC API can support OpenRPC by implementing a service discovery method named `rpc.discover`, which returns the OpenRPC schema for the API; the `rpc.` prefix is reserved for JSON-RPC 2.0 specification system extensions.<sup>[11](https://spec.open-rpc.org/)</sup> OpenRPC is Apache-licensed and is used by organizations including the [Ethereum Foundation](https://www.edgepedia.org/ethereum-foundation), MetaMask, Chainlink, Filecoin, Celestia, and Starknet.<sup>[12](https://www.open-rpc.org/docs)</sup>

## Use in Ethereum

Every Ethereum client implements a JSON-RPC specification so that applications can rely on a uniform set of methods regardless of the specific node or client implementation. The Ethereum JSON-RPC is a standard collection of methods that all execution clients implement, and it is the canonical interface between users and the network, allowing downstream tooling to treat different clients as swappable modules.<sup>[3](https://ethereum.org/developers/docs/apis/json-rpc/)</sup><sup> • </sup><sup>[13](https://ethereum.github.io/execution-apis/docs/quickstart/)</sup>

Ethereum adds its own encoding conventions on top of the protocol. Two key data types pass over JSON: unformatted byte arrays and quantities, both hex encoded. Quantities are encoded as hex with a "0x" prefix in the most compact representation, with zero represented as "0x0"; for example, 0x41 is 65 in decimal and 0x400 is 1024.<sup>[3](https://ethereum.org/developers/docs/apis/json-rpc/)</sup> Core methods fall into three categories: Gossip methods such as `eth_blockNumber` and `eth_sendRawTransaction` track the head of the chain, State methods report current stored data, and History methods cover past data.<sup>[3](https://ethereum.org/developers/docs/apis/json-rpc/)</sup> Consensus clients expose a separate Beacon API, and the Engine API handles internal communication between a node's consensus and execution clients.<sup>[3](https://ethereum.org/developers/docs/apis/json-rpc/)</sup> Newer Ethereum standards extend the pattern: ERC-7769 defines a JSON-RPC API for account abstraction under ERC-4337, with debug functions required for specification test suites but never to be exposed publicly in production.<sup>[14](https://eips.ethereum.org/EIPS/eip-7769)</sup>

## Other deployments

The [Model Context Protocol](https://www.edgepedia.org/model-context-protocol) (MCP), a protocol for connecting large language model applications to tools and data, uses JSON-RPC 2.0 as its message format, with every request and response wrapped as a JSON-RPC 2.0 message.<sup>[4](https://paymentauth.org/draft-payment-transport-mcp-00.pdf)</sup> The United States National Security Agency's security guidance on MCP lists JSON-RPC among the technologies to consider when assessing systems that access or process sensitive data.<sup>[15](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf)</sup> An IETF draft for a host-agent communication protocol mandates JSON-RPC 2.0 over UTF-8 encoded JSON, with line-delimited JSON as the default framing.<sup>[16](https://datatracker.ietf.org/doc/html/draft-sunyi-hacp-protocol-00)</sup>

## JSON-RPC compared with REST and gRPC

JSON-RPC and REST serve different purposes. REST organizes an API around resources and HTTP methods, while JSON-RPC expresses calls to named procedures, which suits APIs whose central operation is executing functions on a server.

## References

1. [JSON-RPC 2.0 Specification, jsonrpc.org](https://www.jsonrpc.org/specification?from=20423&from_column=20423)
2. [JSON-RPC 2.0 Specification, json-rpc.org (JSON-RPC Working Group)](https://www.json-rpc.org/specification)
3. [JSON-RPC API, ethereum.org developer documentation](https://ethereum.org/developers/docs/apis/json-rpc/)
4. [Payment Authentication Scheme: JSON-RPC & MCP Transport (IETF draft)](https://paymentauth.org/draft-payment-transport-mcp-00.pdf)
5. [About JSON-RPC, jsonrpc.org archive](https://www.jsonrpc.org/archive_json-rpc.org/about.html)
6. [JSON-RPC 1.1 Specification, Working Draft 7 August 2006](https://www.jsonrpc.org/historical/json-rpc-1-1-wd.html)
7. [JSON-RPC 1.0 Specification, jsonrpc.org archive](https://www.jsonrpc.org/archive_json-rpc.org/specification.html)
8. [JSON-RPC Developer Guide, OpenDaylight documentation](https://docs.opendaylight.org/projects/jsonrpc/en/latest/dev-guide.html)
9. [draft-yang-json-rpc, IETF Internet-Draft](https://datatracker.ietf.org/doc/html/draft-yang-json-rpc)
10. [Application Note JSON-RPC, Microchip](https://ww1.microchip.com/downloads/en/Appnotes/ENT-AN1126-4.3_VPPD-04260.pdf)
11. [OpenRPC Specification, version 1.4.x](https://spec.open-rpc.org/)
12. [OpenRPC Documentation](https://www.open-rpc.org/docs)
13. [Execution API Specification, Ethereum Execution APIs](https://ethereum.github.io/execution-apis/docs/quickstart/)
14. [ERC-7769: JSON-RPC API for ERC-4337, Ethereum Improvement Proposals](https://eips.ethereum.org/EIPS/eip-7769)
15. [Model Context Protocol: Security Design Considerations, NSA Cybersecurity Information](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf)
16. [draft-sunyi-hacp-protocol-00, IETF Internet-Draft](https://datatracker.ietf.org/doc/html/draft-sunyi-hacp-protocol-00)

---
*Topic: Encyclopedia › Technology and the built world › Computing and digital systems › Software and programming › Data formats and serialization*

*Initially written Sep 17, 2026 · Reviewed: Sep 17, 2026; Sep 30, 2026; Oct 15, 2026 · Edited: Sep 30, 2026; Oct 15, 2026 · Last review: Oct 15, 2026*

*Copyright 2026 EdgeChat AI, a subsidiary of Biostate AI.*

License: Edgepedia Community License 1.0, https://www.edgepedia.org/edgepedia/license