Directives

To instruct eRPC behavior on a per-request basis, you can provide directive "Headers" based on actual use-case:

Retry empty responses

By default all empty-ish responses will be retried, and only if all upstreams return the same empty response, then client will receive the empty response.

Emptyish means any of these:

Response is [] empty array for example for eth_getLogs
Response is null or {} empty object for example for eth_getTransactionReceipt
Response is "" or 0x empty hashed byte, for example for certain eth_call responses

To explicitly disable this behavior for certain requests, you can use either:

Header X-ERPC-Retry-Empty: false
Or query parameter ?retry-empty=false

Empty-response retry behavior only applies when dealing with unfinalized data (recent blocks). For blocks in far past, empty responses are treated as final and won't be retried.

For example when you're requesting eth_getTransactionReceipt of mostly reecent transactions and prefer to immeditely get an empty response and handle it on your client side:

curl --location 'http://localhost:4000/main/evm/42161' \
--header 'Content-Type: application/json' \
--header 'X-ERPC-Retry-Empty: false' \
--data '{
    "method": "eth_getTransactionReceipt",
    "params": [
        "0xe014f359cb3988f9944cd8003aac58812730383041993fdf762efcee21172d15",
    ],
    "id": 9199,
    "jsonrpc": "2.0"
}'
 
# OR
curl --location 'http://localhost:4000/main/evm/42161?retry-empty=false'
# ...

Retry pending transactions

By default requests towards pending transactions will be retried until tx is included (blockNumber is not null), and fail if even after all retries blockNumber is still null.

This behavior is applied to these methods:

eth_getTransactionByHash
eth_getTransactionByBlockHashAndIndex
eth_getTransactionByBlockNumberAndIndex
eth_getTransactionReceipt

To disable this behavior, you can use either:

Header X-ERPC-Retry-Pending: false
Or query parameter ?retry-pending=false

For example if you're intentionally looking to query data of pending transactions (e.g. MEV bot) and prefer to immeditely get the pending tx data:

curl --location 'http://localhost:4000/main/evm/42161' \
--header 'Content-Type: application/json' \
--header 'X-ERPC-Retry-Pending: false' \
--data '{
    "method": "eth_getTransactionReceipt",
    "params": [
        "0xe014f359cb3988f9944cd8003aac58812730383041993fdf762efcee21172d15",
    ],
    "id": 9199,
    "jsonrpc": "2.0"
}'
 
# OR
curl --location 'http://localhost:4000/main/evm/42161?retry-pending=false'
# ...

Pending transactions (with blockNumber of null) are not stored in cache because they are not guaranteed to be included in any block.

Skip cache read

To instruct eRPC to skip 'reading' responses from cache, and make actual calls to upstreams. This directive is "false" by default, which means cache will be used. Useful when you need to force-refresh some data or override an already cached response.

Header X-ERPC-Skip-Cache-Read: true
Or query parameter ?skip-cache-read=true

curl --location 'http://localhost:4000/main/evm/42161' \
--header 'Content-Type: application/json' \
--header 'X-ERPC-Skip-Cache-Read: true' \
--data '{
    "method": "eth_getTransactionReceipt",
    "params": [
        "0xe014f359cb3988f9944cd8003aac58812730383041993fdf762efcee21172d15",
    ],
    "id": 9199,
    "jsonrpc": "2.0"
}'
 
# OR
curl --location 'http://localhost:4000/main/evm/42161?skip-cache-read=true'
# ...

The new response will still be subject to caching as per usual.

Use specific upstream(s)

When sending requests to eRPC you can instruct to use only one specific upstream (or multiple via wildcard match) using:

Header X-ERPC-Use-Upstream: <xxx>
Or query parameter ?use-upstream=<xxx>

This will skip over any upstream that does not match the value you've provided.

You can use * as wildcard character to match a group of upstreams. e.g. "priv-*" will match any upstream IDs starting with "priv-"

For example if you want to make sure that request is sent to a specific upstream:

curl --location 'http://localhost:4000/main/evm/42161' \
--header 'Content-Type: application/json' \
--header 'X-ERPC-Use-Upstream: up123' \
--data '{
    "method": "eth_getTransactionReceipt",
    "params": [
        "0xe014f359cb3988f9944cd8003aac58812730383041993fdf762efcee21172d15",
    ],
    "id": 9199,
    "jsonrpc": "2.0"
}'
 
# OR
curl --location 'http://localhost:4000/main/evm/42161?use-upstream=up123'
# ...

Batching Production