URL

eRPC supports several URL patterns for making requests, with options for both single-chain and multi-chain endpoints.

Single-chain requests

Standard URL pattern

When making requests only for a single chain, you can use this URL structure:

https://<your-erpc-hostname>/<project-id>/<network-architecture>/<chain-id>

`<your-erpc-hostname>`

Depends on your deployment setup, for example in local development (using make run) it will be localhost:4000.

`<project-id>`

Target project ID you configured in erpc.yaml, for example "main" or "frontend", "backend", etc.

`<network-architecture>`

Target network architecture you configured in erpc.yaml, for example evm.

`<chain-id>`

Target chain ID that one or more upstreams support, for example 1 or 42161.

# A cURL example of sending a request to a project named "main" and Ethereum mainnet chain:
 
curl --location 'http://localhost:4000/main/evm/1' \
--header 'Content-Type: application/json' \
--data '{
    "method": "eth_getBlockByNumber",
    "params": [
        "0x1203319",
        false
    ],
    "id": 9199,
    "jsonrpc": "2.0"
}'

Domain aliasing

If configured with domain aliasing, you can have predefined project and network values:

erpc.yaml

server:
  # ...
  aliasing:
    rules:
      - matchDomain: "*" # (OPTIONAL) Pattern to match Host header, defaults to `*` (all domains)
        serveProject: "main" # (OPTIONAL) Project ID to serve for matched domains
        serveArchitecture: "evm" # (OPTIONAL) Network architecture (e.g., "evm")
        serveChain: "1" # (OPTIONAL) Chain ID (e.g., "1" for Ethereum mainnet)

Configuration examples

No aliasing - full URL is required

aliasing: ~

https://api.myservice.com/main/evm/1

Project only

server:
  aliasing:
    rules:
      - matchDomain: "api.myservice.com"
        serveProject: "main"

https://api.myservice.com/evm/1

Project and architecture

server:
  aliasing:
    rules:
      - matchDomain: "evm.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"

https://evm.myservice.com/1

Full aliasing

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

https://eth.myservice.com

Multiple rules example

You can define multiple rules to handle different domains:

server:
  aliasing:
    rules:
      # Ethereum Mainnet specific endpoint
      - matchDomain: "eth.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"
        serveChain: "1"
      
      # Arbitrum specific endpoint
      - matchDomain: "arbitrum.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"
        serveChain: "42161"
      
      # Generic EVM endpoint (requires chain ID in URL)
      - matchDomain: "evm.myservice.com"
        serveProject: "main"
        serveArchitecture: "evm"
      
      # Project-specific endpoint (requires architecture and chain in URL)
      - matchDomain: "api.myservice.com"
        serveProject: "main"

Alias domains are matched with Host header using matcher syntax

Multi-chain requests

When making requests for multiple chains, you can use the project endpoint only and must include "networkId" within the request body:

https://<your-erpc-hostname>/<project-id>

# A cURL example of sending a request to a project named "main" and Ethereum mainnet chain:
 
curl --location 'http://localhost:4000/main' \
--header 'Content-Type: application/json' \
--data '{
    "networkId": "evm:1",
    "method": "eth_getBlockByNumber",
    "params": [
        "0x1203319",
        false
    ],
    "id": 9199,
    "jsonrpc": "2.0"
}'

Batch requests

You can batch multiple calls across any number of networks, in a single request. Read more about it in Batch requests page.

Healthcheck

eRPC has a built-in /healthcheck endpoint that can be used to check the health of the service within Kubernetes, Railway, etc.

Global healthcheck

Check the health of all projects and their upstreams:

curl http://localhost:4000/healthcheck -v
# < HTTP/1.1 200 OK
# OK

This endpoint checks active projects and their upstreams (i.e. those which received at least 1 request) for total error rate, and it will return a non-200 response if all endpoints have a +99% error rate.

Project-specific healthcheck

Check the health of a specific project and network:

curl http://localhost:4000/main/evm/1/healthcheck -v
# < HTTP/1.1 200 OK
# OK

The healthcheck endpoints verify active upstreams (i.e. those which received at least 1 request) for total error rate, and will return a non-200 response if all endpoints have a +99% error rate. For project-specific healthchecks, only the upstreams for the specified network are checked.

Aliasing healthcheck

If you have configured domain aliasing, you can append the /healthcheck to the URL:

# When aliasing is NOT used:
curl http://eth.myapi.com/main/evm/42161/healthcheck -v
 
# When only project is aliased:
curl http://eth.myapi.com/evm/42161/healthcheck -v
 
# When only project and network architecture is aliased:
curl http://eth.myapi.com/42161/healthcheck -v
 
# When all project, network architecture and chain are aliased:
curl http://eth.myapi.com/healthcheck -v

Cloud Batching