URL & routing

URL patterns

eRPC supports three URL shapes for JSON-RPC over HTTP:

1. Full path (no aliasing required)

POST /<projectId>/<architecture>/<chainId>

Example: POST /main/evm/1

2. Network alias (short name)

POST /<projectId>/<alias>

<alias> must be a network alias configured under the project. Resolves to a specific architecture + chain.

3. Multi-chain project endpoint

POST /<projectId>

The JSON-RPC request body must include a top-level "networkId" field (e.g. "evm:1") to identify the target chain.

HTTP methods

Only POST is supported for JSON-RPC requests. GET and OPTIONS (for CORS preflight) are handled by the server but do not dispatch JSON-RPC.

Request body formats

Single JSON-RPC request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_blockNumber",
  "params": []
}

JSON-RPC batch (array):

[
  {"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]},
  {"jsonrpc":"2.0","id":2,"method":"eth_gasPrice","params":[]}
]

Multi-chain single request (project endpoint only):

{
  "jsonrpc": "2.0",
  "id": 1,
  "networkId": "evm:42161",
  "method": "eth_blockNumber",
  "params": []
}

Multi-chain batch (project endpoint only):

[
  {"jsonrpc":"2.0","id":1,"networkId":"evm:1","method":"eth_blockNumber","params":[]},
  {"jsonrpc":"2.0","id":2,"networkId":"evm:42161","method":"eth_blockNumber","params":[]}
]

See Batch requests for full details on multi-chain fan-out and response merging.

Query params and request headers

eRPC supports X-ERPC-* directive headers and query params on every request. These control caching, selection, retries, and hedging at the per-request level. See Directives for the full list.

Common examples:

# Skip cache read (force upstream fetch)
curl ... -H 'X-ERPC-Skip-Cache-Read: true'
 
# Pin to a specific upstream
curl ... -H 'X-ERPC-Use-Upstream: my-alchemy'
 
# Disable retries for this request
curl ... -H 'X-ERPC-Retries: 0'

Server aliasing: AliasingConfig

server.aliasing.rules[] maps Host headers to project/architecture/chain values. Rules are evaluated in order; the first match wins.

All fields are optional. Fields not set in the rule are still required in the URL path. Example with multiple rules:

server:
  aliasing:
    rules:
      - matchDomain: "eth.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"
        serveChain: "1"
      - matchDomain: "arbitrum.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"
        serveChain: "42161"
      - matchDomain: "evm.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"
      - matchDomain: "api.myservice.com"
        serveProject: "main"

Network alias usage

Network aliases are short names configured inside a project's networks[] block. When a caller uses POST /<projectId>/<alias>, eRPC resolves the alias to its architecture + chain ID before routing. Aliases let you expose a stable name (mainnet, arbitrum) that is independent of the numeric chain ID — useful if you ever need to remap chains without updating all callers.

Healthcheck endpoint

GET /healthcheck returns 200 OK when eRPC is ready. During graceful shutdown (after SIGTERM + waitBeforeShutdown), it returns 503. See Healthcheck for details.

Admin endpoint

POST /admin exposes the JSON-RPC admin API (project inspection, API-key CRUD). See Admin API.

Common pitfalls

• Trailing slashes — /main/evm/1/ (with a trailing slash) is not the same as /main/evm/1. eRPC does not redirect; the request will 404 or be misrouted.
• Case sensitivity — project IDs, architecture names, and chain IDs in the path are matched case-sensitively. EVM vs evm and Main vs main are different.
• Alias collisions — if a network alias has the same string as a numeric chain ID (e.g. an alias named "1"), the numeric chain ID takes precedence in the path resolver. Name aliases distinctly (e.g. "mainnet", "arbitrum").
• matchDomain: "*" catches everything — if you define a wildcard rule before a more specific one, the wildcard fires first. Put specific rules before the catch-all.
• networkId required at project endpoint — calling POST /main without a networkId field in the body will result in a routing error. Only use the project endpoint when you need multi-chain dispatch.
• Domain aliasing and Host header forwarding — when running behind a reverse proxy, ensure the proxy forwards the original Host header (not localhost or the upstream address). Most proxies need proxy_set_header Host $host; (nginx) or equivalent.