JSON-RPC has no built-in authentication, authorisation or rate limiting, so every JSON-RPC endpoint is only as safe as the method allow list, batch limits and caller identity checks its operator adds around it. JSON-RPC 2.0 is a small, stateless remote procedure call protocol. It sits underneath Ethereum execution client APIs, many internal service buses, developer tooling and agent protocols. Its simplicity is the attraction and the risk: a single HTTP endpoint can expose every method a process implements, a single request can carry many calls, and nothing in the protocol says who is allowed to call what.
This guide explains the JSON-RPC 2.0 message model from a security point of view, then works through method exposure, batching and notification abuse, caller authentication for non-human identities, error handling, transport choices and monitoring. It is based on the JSON-RPC 2.0 specification and the ethereum.org JSON-RPC API documentation as of November 2026. For a different RPC framework with built-in TLS and interceptors, see the gRPC Security Guide; for agent tool servers that use JSON-RPC messages, see the MCP Security Guide.
Key takeaways
- The JSON-RPC 2.0 specification is transport agnostic and defines no security. Authentication, authorisation, TLS and limits are entirely the implementer's job.
- Method exposure is the main risk. Every registered method is reachable unless an allow list blocks it, and administrative or signing methods must never share an endpoint with public read methods.
- Batches let one HTTP request carry many calls, which the server may process concurrently. Cap batch size and count each call against rate limits, not each HTTP request.
- Notifications produce no response, even on error, so failed or abusive calls can be invisible to the caller and to naive monitoring.
- Authenticate callers at the transport or gateway, then authorise per method and per parameter. Treat API keys for RPC endpoints as high-value non-human credentials.
- Exposed blockchain node RPC endpoints are a recurring incident pattern: keep signing and account methods off any reachable interface.
The JSON-RPC 2.0 model through a security lens
The specification describes JSON-RPC as stateless and light-weight, and says it is transport agnostic: the same messages can be used within one process, over sockets, over HTTP or in other message passing environments. That portability is why the protocol appears in so many places, and also why it carries no assumptions about identity or confidentiality.
A request object has four members. jsonrpc must be exactly "2.0". method is a string naming the procedure, and names beginning with rpc. are reserved for internal methods and extensions. params is optional and, when present, must be structured, either an array of positional values or an object of named values. id is optional; if present it must be a string, number or null, and the server echoes it in the response.
Three properties of this model drive most of the security work:
- The method name is data. The caller chooses which procedure to run by sending a string. Routing is whatever the server's dispatcher does with that string, so dispatch must be an explicit table, never reflection over an object or module.
- A request without an
idis a notification. The specification says the server must not reply to notifications, including those inside a batch, and that the client therefore cannot learn about errors such as invalid parameters. - A request can be an array. A batch carries many request objects in a single call, and the server may process them concurrently and in any order.
Nothing in the request identifies the caller. Identity has to come from the transport (a TLS client certificate, an HTTP Authorization header, a Unix socket's file permissions, a parent process) or from a gateway in front of the service.
Where JSON-RPC shows up
Knowing where JSON-RPC runs in your estate is the first control. Common locations include:
- Ethereum execution clients. ethereum.org documents that every Ethereum execution client implements a JSON-RPC specification so applications can use a uniform set of methods across clients. Its examples send requests to
127.0.0.1:8545and note that most clients default to serving onlocalhost:8545. The same page separates the execution client API from the consensus client Beacon API and from the internal Engine API used between consensus and execution clients. - Agent and developer tooling. Agent tool protocols and editor language servers commonly frame their messages as JSON-RPC. Where these run over local pipes, the parent process is the trust boundary; where they run over HTTP, the endpoint needs the same controls as any other API.
- Internal services. Some teams use JSON-RPC over HTTP or WebSockets as a lightweight alternative to REST or gRPC for service-to-service calls, often behind assumptions that the network is private.
- Appliances and embedded management interfaces. Device and storage management planes sometimes expose JSON-RPC for their administrative user interface.
Inventory each endpoint with its transport, listening address, the methods it exposes, who or what calls it, and which credential that caller presents. Endpoints that nobody can account for are the ones that end up exposed.
Method exposure and allow lists
A JSON-RPC server is a dispatcher from method names to code. The safest pattern is a deny-by-default allow list per endpoint and per caller class, with administrative methods served on a separate listener that is not reachable from the same network as public clients.
Classify methods by consequence
Group every method into tiers before deciding exposure:
| Tier | Examples | Exposure guidance |
|---|---|---|
| Read, public data | Chain height, block lookups, version strings | May be exposed to authenticated or anonymous clients with rate limits. |
| Read, expensive | Log range queries, historical state, trace or debug calls | Require authentication, cap ranges and result sizes, and limit concurrency. |
| State changing | Submitting signed transactions, creating jobs, writing records | Authenticated callers only, with per-caller quotas and audit logging. |
| Signing or key use | Methods that sign with a key held by the server | Never on a network-reachable endpoint. Keep keys out of the RPC process where possible. |
| Administrative | Peer management, configuration, shutdown, account unlocking | Local IPC or a dedicated management network only, with strong authentication. |
The Ethereum documentation illustrates why the signing tier matters. It describes eth_sign and eth_sendTransaction, which sign with an account held by the node, and notes that for eth_sign the address to sign with must be unlocked. A node that holds unlocked accounts and exposes these methods on a reachable interface lets any caller spend from those accounts. The safer architecture keeps keys in a separate signer or wallet and sends only pre-signed transactions through eth_sendRawTransaction. The Web3 and Crypto Security Guide covers key custody in more depth.
Implementation rules
- Dispatch through an explicit map of method names to handlers. Never resolve method names through reflection, dynamic imports or attribute lookups, which can expose internal functions.
- Reject method names outside the allow list with the standard
-32601Method not found error, whether the method exists or not, so that probing cannot distinguish disabled from absent methods. - Do not implement
rpc.prefixed discovery or introspection methods on production endpoints unless they are needed and authenticated. - Use separate listeners, or separate URL paths enforced at a gateway, for each tier. Bind administrative listeners to loopback or a Unix socket.
- Keep client defaults that bind to
localhost. When a node must be reachable, put an authenticating proxy in front instead of rebinding the node itself to all interfaces.
Batching and notification abuse
Batching is a legitimate performance feature and a reliable amplification tool. The specification allows a client to send an array of request objects, says the server returns an array of responses with no entries for notifications, and permits the server to process batch items concurrently and in any order. An empty array is invalid and must produce a single Invalid Request error. If every item is a notification, the server returns nothing.
Abuse patterns
- Rate limit bypass. A limiter that counts HTTP requests lets a caller send one request containing thousands of calls.
- Credential and parameter guessing. Batches multiply the guesses per request for any method that validates a secret, token or identifier, which defeats per-request lockouts.
- Resource exhaustion. Concurrent processing of a large batch of expensive reads, such as wide log range queries, can saturate CPU, memory or storage I/O.
- Silent work. A batch of notifications produces no response at all, so the caller gets no feedback and simple response-based monitoring sees nothing.
- Response size amplification. A small request that asks for large objects many times produces a response far larger than the request.
Controls
- Set a maximum batch length per endpoint and reject larger batches before parsing their members. Many services need single-digit or low double-digit batch sizes.
- Apply the overall HTTP body size limit before JSON parsing, and a separate limit on total response size.
- Count each call in a batch against the caller's rate limit and quota, weighted by method cost.
- Limit concurrency per batch and per caller, so a batch cannot occupy every worker.
- Decide whether notifications are needed at all. If an endpoint has no legitimate use for them, reject requests without an
id. If notifications are allowed, log and meter them like any other call. - Apply authentication and authorisation to every call in a batch individually. Never authorise the batch on the first item alone.
The Rate Limiting and API Abuse Guide and the OWASP API Top 10 API4 Unrestricted Resource Consumption Guide describe quota design that applies directly to JSON-RPC.
Authenticating callers and protecting RPC credentials
Because the protocol carries no identity, the choice of authentication follows the transport:
- Local pipes and Unix sockets. Rely on file system permissions and process ownership. Restrict the socket to the service account that needs it.
- HTTP and WebSockets. Require TLS, then authenticate with OAuth access tokens, signed JWTs or mutual TLS client certificates. Validate tokens against RFC 8725 JSON Web Token Best Current Practices, including algorithm pinning and audience checks.
- Gateways. A reverse proxy or API gateway can authenticate the caller, then pass a verified identity to the RPC service. The service must accept that identity only from the gateway, never from a header a client can set directly.
Authorise per method and per parameter
Authentication tells you which service is calling; authorisation decides what it may do. Map each caller identity to an allowed set of methods, and for methods that act on objects, check that the caller may act on the specific object named in params. This is the JSON-RPC form of object level authorisation, and it matters because method parameters are fully attacker controlled. Validate params against a strict schema per method, rejecting unknown named parameters and out-of-range values with -32602 Invalid params.
RPC credentials are non-human identities
Hosted node providers and internal RPC gateways typically issue API keys that appear in URLs or headers. These keys are often copied into front-end code, CI variables, bots and scripts, and the leaked key then gives full access to whatever methods and quota the key allows. Treat them as managed non-human identities:
- Issue one key per calling workload, never a shared team key, so usage and revocation are traceable.
- Scope keys to the methods and origins each workload needs, where the provider or gateway supports it.
- Prefer headers to URL query parameters, because URLs are logged by proxies, browsers and analytics tools.
- Store keys in a secrets manager, rotate them on a schedule and on staff or vendor changes, and scan repositories for them.
- Alert on use from unexpected networks or at unusual volumes.
MITRE ATT&CK tracks the theft and misuse of such credentials as Steal Application Access Token (T1528), and exposed endpoints are reached through Exploit Public-Facing Application (T1190).
Error handling and information disclosure
The specification defines an error object with an integer code, a short message and an optional server-defined data member. It reserves codes from -32768 to -32000 for predefined errors:
| Code | Message | Meaning |
|---|---|---|
| -32700 | Parse error | Invalid JSON was received. |
| -32600 | Invalid Request | The JSON is not a valid request object. |
| -32601 | Method not found | The method does not exist or is not available. |
| -32602 | Invalid params | Invalid method parameters. |
| -32603 | Internal error | Internal JSON-RPC error. |
| -32000 to -32099 | Server error | Reserved for implementation-defined server errors. |
The optional data member is where leaks happen. Implementations commonly place stack traces, SQL fragments, file paths, upstream URLs or internal hostnames there during development and never remove them. Return minimal messages to callers and send the detail to server-side logs keyed by a correlation ID. Use the same error for "method does not exist" and "method exists but this caller may not use it", and avoid authorisation-specific messages that confirm a method or object exists. The Exposed Debug Modes Guide covers the related failure of shipping verbose diagnostics to production.
Transport, browser and network exposure
JSON-RPC over HTTP is usually a POST with a JSON body. The ethereum.org examples note that some nodes reject requests whose content type is not application/json. Enforcing that content type on every endpoint is worthwhile, because browsers can send simple cross-origin form posts without a preflight but cannot send a JSON content type cross-origin without one.
Network and browser controls to apply:
- Bind narrowly. Listen on loopback or a private interface. Treat any change to listen on all interfaces as a reviewed change.
- Restrict CORS. Do not allow wildcard origins on endpoints with state-changing or signing methods. A local RPC server with permissive CORS can be driven by any web page the operator visits.
- Validate the Host header on local endpoints, to reduce DNS rebinding risk, where your server or proxy supports it.
- Use TLS for anything that leaves the host, and mutual TLS for service-to-service calls where practical.
- Separate WebSocket subscriptions from request endpoints and cap the number of subscriptions per connection and per caller, because long-lived subscriptions consume server state.
- Segment node infrastructure. Keep execution, consensus and Engine API interfaces on separate, minimally reachable networks, following each client's documentation.
The API Security Guide covers gateway and network patterns shared with REST APIs.
Monitoring and detection
JSON-RPC traffic looks uniform at the HTTP layer: the same path and method for every call. Useful monitoring therefore needs visibility inside the body. Log, for every call, the authenticated caller identity, method name, batch size and position, whether it was a notification, result or error code, latency and response size. Avoid logging full params for methods that carry secrets or signed payloads.
Signals worth alerting on, as illustrative starting points:
- Any call to an administrative, signing or account method from a network caller.
- Spikes in
-32601Method not found errors from one caller, which suggest method enumeration. - Batch sizes near or above the configured cap, or sudden growth in calls per HTTP request.
- High volumes of notifications from callers that normally send requests.
- Use of an RPC API key from a new network, region or user agent.
- Unusually expensive query parameters, such as very wide block or time ranges.
Common failure patterns
- Node RPC exposed to the internet. A blockchain node or management service rebound to all interfaces for convenience, with signing or administrative methods enabled.
- Reflection-based dispatch. Method names resolved against an object or module, exposing internal helpers as remote procedures.
- Per-request rate limits. Limits that count HTTP requests rather than calls, defeated by batching.
- Batch authorised once. Authorisation checked on the first item of a batch and assumed for the rest.
- Verbose
datain errors. Stack traces and internal addresses returned to callers. - Shared provider keys. One RPC provider key embedded in a front end, a bot and CI, with no way to tell callers apart or revoke one without breaking all.
- Trusting the network. Internal JSON-RPC services with no authentication because they are "only on the private network".
Practitioner checklist
- Inventory every JSON-RPC endpoint with its transport, bind address, exposed methods, callers and credentials.
- Implement deny-by-default method allow lists per endpoint and per caller, with administrative and signing methods on local-only listeners.
- Keep keys out of RPC-serving processes; send pre-signed transactions instead of using server-side signing methods.
- Cap batch length, body size, response size and per-batch concurrency, and rate limit each call by caller identity.
- Reject or meter notifications, and authorise every call in a batch individually.
- Require TLS and caller authentication on every network endpoint, and validate
paramsagainst a strict schema per method. - Return minimal errors using the standard codes, and keep diagnostic detail in server logs.
- Issue one scoped, rotated RPC credential per workload, and keep it out of URLs and front-end code.
- Log method, caller, batch size and error code for every call, and alert on administrative method use and method enumeration.
Standards and references
- JSON-RPC 2.0 Specification
- ethereum.org: JSON-RPC API documentation
- OWASP: API Security Top 10 2023
- OWASP: Application Security Verification Standard 5.0
- IETF: RFC 8725 JSON Web Token Best Current Practices
- NIST: SP 800-53 Rev. 5 (AC-6 Least Privilege, SC-5 Denial-of-service Protection, SI-10 Information Input Validation)
- MITRE ATT&CK: Exploit Public-Facing Application
- MITRE ATT&CK: Steal Application Access Token
Related NHI Mgmt Group resources: gRPC Security Guide · MCP Security Guide · API Security Guide · Web3 and Crypto Security Guide