Skip to main content
Boost reads the JSON-RPC method and parameters, then chooses the response source. The API key identifies your project’s Boost; that project’s network configuration supplies the upstream for calls that need your provider.

​
Routing model

A failed or incomplete cache lookup falls back to your upstream. A cache miss can add proxy latency, but it does not substitute a different result.

​
Methods eligible for indexed data

Eligibility does not guarantee a hit. If Goldsky does not have the requested data, Boost forwards the request.

​
Tip of chain

eth_blockNumber and eth_getBlockByNumber with latest are answered from Goldsky’s indexed data, which follows your source chain at the tip and through reorgs. Other tags forward: pending, safe, finalized, and earliest on any method, and latest on methods other than eth_getBlockByNumber. The same rule applies to eth_getLogs when either range bound is a tag. Use a concrete hexadecimal height when you want those reads served by Boost.

​
Everything else forwards

Writes, traces, and state reads such as eth_call and eth_getBalance go to your configured upstream. Boost also forwards methods it does not recognize as eligible. For a forwarded call, Boost preserves the JSON-RPC method, parameters, and ID. The result body comes from your upstream. HTTP headers are handled separately; see request and response forwarding.

​
Cache-only mode

Add cache-only=true and Boost never contacts your upstream. Calls it can answer from Goldsky data are answered; everything that would otherwise forward returns JSON-RPC error -32099 instead. Use it when the forward is the cost you are avoiding. Boost itself is free, but a forwarded call still reaches the provider you pay. A backfill, a replay, or any job with a spending ceiling can run against indexed data alone and retry the gaps later. Send it as a query parameter or a header. The two are equivalent:
A refused call returns:
Boost returns an error rather than an empty result on purpose. null already carries meaning here — eth_getTransactionReceipt returns null for a transaction that does not exist — so answering a miss with null would report an absence that Goldsky never verified. Repeat the call without the flag to forward it normally. eth_chainId and net_version still answer under cache-only, because Boost synthesizes them and no provider is involved either way. Refused calls report x-edge-source: none: not endpoint, since nothing reached your upstream. In a batch, the flag applies per item. Eligible items are served and the rest are refused individually, in one response array.

​
Skip-cache

The inverse: skip-cache=true, or the x-boost-skip-cache: true header, forwards the call to your upstream without reading the cache. Use it to time your provider directly or to fetch a value the cache would otherwise answer. Statics still answer at the edge. The next call without the flag is served from cache as usual; nothing is invalidated.
Write either value as exactly true. 1, TRUE, yes, and a bare flag all read as “not requested”. Sending both flags on one request returns -32600; they contradict.

​
Batch requests

Boost evaluates JSON-RPC batches per item. Eligible items can come from Goldsky data while the remaining items are sent to your upstream together in one onward batch.
  • Give every item a unique id. JSON-RPC does not guarantee response order, so match results by ID.
  • Use x-edge-billable as the served-item count. x-cache is HIT only when Boost serves every item in the batch.
  • Keep arrays at 100 items or fewer. Larger arrays are forwarded whole without cache lookups.
For example, a batch where Boost serves 44 of 45 items reports x-cache: MISS and x-edge-billable: 44.

​
Authentication and endpoint selection

The endpoint format is:
The chain path selects the network. The Goldsky key identifies your project’s Boost, and that network’s configuration selects the active upstream. Your provider URL and persistent provider credentials stay in the configuration rather than traveling in each request.