# eRPC documentation — full reference > Source: https://docs.erpc.cloud/ > This file is the AI-friendly entry point for the eRPC documentation. > It contains the home page content, the full navigation tree, and a > flat list of every page — each linked to its own machine-readable > companion at `.llms.txt`. Append `.llms.txt` to any docs URL > to fetch that page's expanded markdown (all collapsible AI sections > inlined). Internal links inside `.llms.txt` files also point at > `.llms.txt` so an AI agent can crawl the entire reference without > leaving the machine-readable surface. --- ## Home page # Introducing eRPC eRPC is a fault-tolerant EVM RPC proxy and permanent caching solution. It is built with read-heavy use-cases in mind such as data indexing and high-load frontend usage. # Quick start ### Create configuration Create your [`erpc.yaml`](/config/example.llms.txt) configuration file based on the `erpc.dist.yaml` file: ```bash cp erpc.dist.yaml erpc.yaml code erpc.yaml ``` See [a complete config example](/config/example.llms.txt) for inspiration. ### Run with Docker Use the Docker image: ```bash docker run -v $(pwd)/erpc.yaml:/erpc.yaml -p 4000:4000 -p 4001:4001 ghcr.io/erpc/erpc:latest ``` ### Test the setup Send your first request: ```bash curl --location 'http://localhost:4000/main/evm/42161' \ --header 'Content-Type: application/json' \ --data '{ "method": "eth_getBlockByNumber", "params": [ "0x1203319", false ], "id": 9199, "jsonrpc": "2.0" }' ``` ### Setup monitoring (optional) Bring up monitoring stack (Prometheus, Grafana) using docker-compose: ```bash # clone the repo if you haven't git clone https://github.com/erpc/erpc.git cd erpc # bring up the monitoring stack docker-compose up -d ``` ### Access Grafana Open Grafana at [http://localhost:3000](http://localhost:3000) and login with the following credentials: - username: `admin` - password: `admin` ### Monitor metrics Send more requests and watch the metrics being collected and visualized in Grafana. ![eRPC Grafana Dashboard](/assets/monitoring-example-erpc.png.llms.txt) --- ## Navigation The same hierarchy a reader sees in the docs sidebar — every leaf links to its `.llms.txt` companion. - [Quick start](https://docs.erpc.cloud/index.llms.txt) - [Why eRPC?](https://docs.erpc.cloud/why.llms.txt) — Main use-cases — cost reduction, fault tolerance, observability, and EVM-aware load balancing. - [Free & Public RPCs](https://docs.erpc.cloud/free.llms.txt) — Run an eRPC proxy against 2,000+ chains and 4,000+ free public RPC endpoints with zero config. - [FAQ](https://docs.erpc.cloud/faq.llms.txt) — Frequently asked questions about running, configuring, and troubleshooting eRPC. ### Config - [erpc.yaml/ts](https://docs.erpc.cloud/config/example.llms.txt) — A tour of every top-level section in an eRPC config — logLevel, server, metrics, database, projects, upstreams, networks, failsafe, and rateLimiters — with minimal and full examples in YAML and TypeScript. - [Server](https://docs.erpc.cloud/config/server.llms.txt) — HTTP + gRPC listeners, TLS, timeouts, shutdown grace, trusted-proxy IP detection, response headers, error-detail controls, and domain-based project aliasing. - **Projects** - [Networks](https://docs.erpc.cloud/config/projects/networks.llms.txt) — A network is a chain (`evm:1`, `evm:42161`, …) and how eRPC serves it — failsafe, selection, integrity, static responses, aliasing. - [Upstreams](https://docs.erpc.cloud/config/projects/upstreams.llms.txt) — An upstream is one or more RPC endpoints that serve one or more EVM networks — with failsafe, rate limits, scoring, block-availability bounds, and per-method filters. - [Providers](https://docs.erpc.cloud/config/projects/providers.llms.txt) — One-line endpoints that fan out across every chain a third-party RPC vendor supports. - [Selection policy](https://docs.erpc.cloud/config/projects/selection-policies.llms.txt) — One JavaScript function per network decides which upstreams serve which methods, in what order. Order is law — missing means excluded. - [CORS](https://docs.erpc.cloud/config/projects/cors.llms.txt) — Configure Cross-Origin Resource Sharing (CORS) per project so browser-based frontends can call eRPC directly — control which origins, methods, and headers are permitted. - **Failsafe** - [Timeout](https://docs.erpc.cloud/config/failsafe/timeout.llms.txt) — Bound how long a request may take — fixed or quantile-adaptive, with per-method and per-finality scoping. - [Retry](https://docs.erpc.cloud/config/failsafe/retry.llms.txt) — Replay transient failures with backoff — empty-result handling, network-scope failover, per-method scoping. - [Hedge](https://docs.erpc.cloud/config/failsafe/hedge.llms.txt) — Race a backup request to a second upstream when the primary is slow — quantile-adaptive delay with min/max guard rails. - [Consensus](https://docs.erpc.cloud/config/failsafe/consensus.llms.txt) — Consensus policy compares responses from multiple upstreams and returns the agreed result, detecting misbehaving nodes and providing deterministic behavior during faults. - [Integrity](https://docs.erpc.cloud/config/failsafe/integrity.llms.txt) — Integrity directives enforce block tracking, response validation, and empty/missing-data handling. Configure via directiveDefaults on networks or per-request headers. - [Circuit breaker](https://docs.erpc.cloud/config/failsafe/circuit-breaker.llms.txt) — How eRPC trips a failing upstream out of rotation — via the Selection Policy's excludeIf chain. - **Database** - [Drivers](https://docs.erpc.cloud/config/database/drivers.llms.txt) — Drivers define the storage backend for the eRPC cache — memory, Redis, PostgreSQL, DynamoDB. Each driver has its own timing, pool, and lock-retry knobs. - [EVM Cache](https://docs.erpc.cloud/config/database/evm-json-rpc-cache.llms.txt) — Cache JSON-RPC responses across one or more storage backends — non-blocking, finality-aware, reorg-safe. - [sharedState](https://docs.erpc.cloud/config/database/shared-state.llms.txt) — Share critical blockchain state across multiple eRPC instances — eliminates redundant upstream polling and improves integrity checks in horizontal-scaling deployments. - [Auth](https://docs.erpc.cloud/config/auth.llms.txt) — Each project can have one or more authentication strategies (secret, network/CIDR, JWT, SIWE, x402 pay-per-request) with per-method filters and rate limits. - [Rate limiters](https://docs.erpc.cloud/config/rate-limiters.llms.txt) — Define shared budgets with per-method rules and assign them to projects, networks, upstreams, or auth strategies. Backed by Redis (distributed) or memory (local). - [Matcher syntax](https://docs.erpc.cloud/config/matcher.llms.txt) — Pattern matching DSL used wherever eRPC compares network/method/param/header values — supports wildcards, OR/AND/NOT, and numeric comparisons over hex/decimal. ### Deployment - [Docker](https://docs.erpc.cloud/deployment/docker.llms.txt) — Deploy eRPC using official Docker images — quick start, docker-compose, custom NPM modules, and production tuning. - [Railway](https://docs.erpc.cloud/deployment/railway.llms.txt) — One-click deploy template for eRPC on Railway. - [Kubernetes](https://docs.erpc.cloud/deployment/kubernetes.llms.txt) — Deploy eRPC on Kubernetes with Deployment, Service, ConfigMap, HPA, and PodDisruptionBudget manifests. - [Cloud](https://docs.erpc.cloud/deployment/cloud.llms.txt) — Managed eRPC instances and cache storage in your preferred region — skip the DevOps overhead. ### Operations - [URL](https://docs.erpc.cloud/operation/url.llms.txt) — URL patterns, request body formats, domain aliasing, and multi-chain batching for eRPC clients. - [Healthcheck](https://docs.erpc.cloud/operation/healthcheck.llms.txt) — Built-in /healthcheck endpoint for Kubernetes readiness probes, liveness probes, and custom upstream health evaluation. - [Batching](https://docs.erpc.cloud/operation/batch.llms.txt) — eRPC deduplicates, fans out, and reassembles JSON-RPC batch requests — both inbound arrays from clients and outbound batches to upstreams. - [Directives](https://docs.erpc.cloud/operation/directives.llms.txt) — Per-request hints that override eRPC behavior — set via HTTP header (X-ERPC-*) or query parameter on any request. - [Production](https://docs.erpc.cloud/operation/production.llms.txt) — Memory/GC tuning, healthcheck rollout, instance identification, error visibility, and IP forwarding recommendations for running eRPC in production. - [Monitoring](https://docs.erpc.cloud/operation/monitoring.llms.txt) — Prometheus metrics for eRPC — enabling the metrics endpoint, cardinality reduction, custom histogram buckets, and the full available metrics reference. - [Tracing](https://docs.erpc.cloud/operation/tracing.llms.txt) — OpenTelemetry tracing for eRPC — OTLP export, sampling, force-trace rules, custom resource attributes. - [Admin](https://docs.erpc.cloud/operation/admin.llms.txt) — JSON-RPC admin endpoint for runtime introspection of eRPC's config, project health, and API-key management. - [Cordoning](https://docs.erpc.cloud/operation/cordoning.llms.txt) — Manually take an upstream out of rotation (and put it back) via the admin RPC — the operator's escape hatch for incident response, vendor maintenance windows, and forced failover testing. - [CLI & env vars](https://docs.erpc.cloud/operation/cli.llms.txt) — eRPC command-line flags, subcommands, and the environment variables that influence runtime behavior. - **Presets** - [DVN (LayerZero)](https://docs.erpc.cloud/presets/dvn-ready.llms.txt) — Minimal eRPC config for DVN operators — multi-provider unanimous consensus on the RPC methods cross-chain message verification depends on. --- ## Every page (flat list) Convenient when an agent wants to iterate over every page rather than follow the hierarchy: - [Authentication](https://docs.erpc.cloud/config/auth.llms.txt) — Each project can have one or more authentication strategies (secret, network/CIDR, JWT, SIWE, x402 pay-per-request) with per-method filters and rate limits. - [config/database/drivers.mdx](https://docs.erpc.cloud/config/database/drivers.llms.txt) — Drivers define the storage backend for the eRPC cache — memory, Redis, PostgreSQL, DynamoDB. Each driver has its own timing, pool, and lock-retry knobs. - [evmJsonRpcCache](https://docs.erpc.cloud/config/database/evm-json-rpc-cache.llms.txt) — Cache JSON-RPC responses across one or more storage backends — non-blocking, finality-aware, reorg-safe. - [sharedState](https://docs.erpc.cloud/config/database/shared-state.llms.txt) — Share critical blockchain state across multiple eRPC instances — eliminates redundant upstream polling and improves integrity checks in horizontal-scaling deployments. - [Complete config example](https://docs.erpc.cloud/config/example.llms.txt) — A tour of every top-level section in an eRPC config — logLevel, server, metrics, database, projects, upstreams, networks, failsafe, and rateLimiters — with minimal and full examples in YAML and TypeScript. - [Failsafe](https://docs.erpc.cloud/config/failsafe.llms.txt) — Per-network and per-upstream failsafe policies — timeout, retry, hedge, consensus, integrity — with per-method and per-finality scoping plus per-attempt observability. - [Circuit breaker](https://docs.erpc.cloud/config/failsafe/circuit-breaker.llms.txt) — How eRPC trips a failing upstream out of rotation — via the Selection Policy's excludeIf chain. - [Consensus](https://docs.erpc.cloud/config/failsafe/consensus.llms.txt) — Consensus policy compares responses from multiple upstreams and returns the agreed result, detecting misbehaving nodes and providing deterministic behavior during faults. - [Hedge](https://docs.erpc.cloud/config/failsafe/hedge.llms.txt) — Race a backup request to a second upstream when the primary is slow — quantile-adaptive delay with min/max guard rails. - [Integrity & Empty Data](https://docs.erpc.cloud/config/failsafe/integrity.llms.txt) — Integrity directives enforce block tracking, response validation, and empty/missing-data handling. Configure via directiveDefaults on networks or per-request headers. - [Retry](https://docs.erpc.cloud/config/failsafe/retry.llms.txt) — Replay transient failures with backoff — empty-result handling, network-scope failover, per-method scoping. - [Timeout](https://docs.erpc.cloud/config/failsafe/timeout.llms.txt) — Bound how long a request may take — fixed or quantile-adaptive, with per-method and per-finality scoping. - [Matcher syntax](https://docs.erpc.cloud/config/matcher.llms.txt) — Pattern matching DSL used wherever eRPC compares network/method/param/header values — supports wildcards, OR/AND/NOT, and numeric comparisons over hex/decimal. - [Projects](https://docs.erpc.cloud/config/projects.llms.txt) — A project bundles a set of networks, upstreams, providers, auth, and rate-limit budgets — one eRPC instance can serve many projects (e.g. backend, indexer, frontend) with different cost/reliability profiles. - [CORS](https://docs.erpc.cloud/config/projects/cors.llms.txt) — Configure Cross-Origin Resource Sharing (CORS) per project so browser-based frontends can call eRPC directly — control which origins, methods, and headers are permitted. - [Networks](https://docs.erpc.cloud/config/projects/networks.llms.txt) — A network is a chain (`evm:1`, `evm:42161`, …) and how eRPC serves it — failsafe, selection, integrity, static responses, aliasing. - [Providers](https://docs.erpc.cloud/config/projects/providers.llms.txt) — One-line endpoints that fan out across every chain a third-party RPC vendor supports. - [Selection policy](https://docs.erpc.cloud/config/projects/selection-policies.llms.txt) — One JavaScript function per network decides which upstreams serve which methods, in what order. Order is law — missing means excluded. - [Upstreams](https://docs.erpc.cloud/config/projects/upstreams.llms.txt) — An upstream is one or more RPC endpoints that serve one or more EVM networks — with failsafe, rate limits, scoring, block-availability bounds, and per-method filters. - [Rate Limiters](https://docs.erpc.cloud/config/rate-limiters.llms.txt) — Define shared budgets with per-method rules and assign them to projects, networks, upstreams, or auth strategies. Backed by Redis (distributed) or memory (local). - [Server](https://docs.erpc.cloud/config/server.llms.txt) — HTTP + gRPC listeners, TLS, timeouts, shutdown grace, trusted-proxy IP detection, response headers, error-detail controls, and domain-based project aliasing. - [Hosted cloud](https://docs.erpc.cloud/deployment/cloud.llms.txt) — Managed eRPC instances and cache storage in your preferred region — skip the DevOps overhead. - [Docker deployment](https://docs.erpc.cloud/deployment/docker.llms.txt) — Deploy eRPC using official Docker images — quick start, docker-compose, custom NPM modules, and production tuning. - [Kubernetes deployment](https://docs.erpc.cloud/deployment/kubernetes.llms.txt) — Deploy eRPC on Kubernetes with Deployment, Service, ConfigMap, HPA, and PodDisruptionBudget manifests. - [Railway](https://docs.erpc.cloud/deployment/railway.llms.txt) — One-click deploy template for eRPC on Railway. - [FAQ](https://docs.erpc.cloud/faq.llms.txt) — Frequently asked questions about running, configuring, and troubleshooting eRPC. - [Free & Public RPCs](https://docs.erpc.cloud/free.llms.txt) — Run an eRPC proxy against 2,000+ chains and 4,000+ free public RPC endpoints with zero config. - [Introducing eRPC](https://docs.erpc.cloud/index.llms.txt) - [Admin API](https://docs.erpc.cloud/operation/admin.llms.txt) — JSON-RPC admin endpoint for runtime introspection of eRPC's config, project health, and API-key management. - [Batch requests](https://docs.erpc.cloud/operation/batch.llms.txt) — eRPC deduplicates, fans out, and reassembles JSON-RPC batch requests — both inbound arrays from clients and outbound batches to upstreams. - [CLI & env vars](https://docs.erpc.cloud/operation/cli.llms.txt) — eRPC command-line flags, subcommands, and the environment variables that influence runtime behavior. - [Cordoning](https://docs.erpc.cloud/operation/cordoning.llms.txt) — Manually take an upstream out of rotation (and put it back) via the admin RPC — the operator's escape hatch for incident response, vendor maintenance windows, and forced failover testing. - [Directives](https://docs.erpc.cloud/operation/directives.llms.txt) — Per-request hints that override eRPC behavior — set via HTTP header (X-ERPC-*) or query parameter on any request. - [Healthcheck](https://docs.erpc.cloud/operation/healthcheck.llms.txt) — Built-in /healthcheck endpoint for Kubernetes readiness probes, liveness probes, and custom upstream health evaluation. - [Monitoring & metrics](https://docs.erpc.cloud/operation/monitoring.llms.txt) — Prometheus metrics for eRPC — enabling the metrics endpoint, cardinality reduction, custom histogram buckets, and the full available metrics reference. - [Production guidelines](https://docs.erpc.cloud/operation/production.llms.txt) — Memory/GC tuning, healthcheck rollout, instance identification, error visibility, and IP forwarding recommendations for running eRPC in production. - [Tracing](https://docs.erpc.cloud/operation/tracing.llms.txt) — OpenTelemetry tracing for eRPC — OTLP export, sampling, force-trace rules, custom resource attributes. - [URL & routing](https://docs.erpc.cloud/operation/url.llms.txt) — URL patterns, request body formats, domain aliasing, and multi-chain batching for eRPC clients. - [Examples](https://docs.erpc.cloud/presets.llms.txt) — Drop-in eRPC config presets for specific scenarios (DVN, indexer, frontend, etc.). - [DVN (LayerZero)](https://docs.erpc.cloud/presets/dvn-ready.llms.txt) — Minimal eRPC config for DVN operators — multi-provider unanimous consensus on the RPC methods cross-chain message verification depends on. - [Why eRPC?](https://docs.erpc.cloud/why.llms.txt) — Main use-cases — cost reduction, fault tolerance, observability, and EVM-aware load balancing.