> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching and deduplication

> How the Gateway caches responses and deduplicates identical in-flight requests.

The Gateway uses two strategies to reduce load on observer nodes and improve response times: TTL-based caching for stable data and in-flight request deduplication for concurrent identical requests.

## TTL caching

Some responses change infrequently. The Gateway caches them with a time-to-live (TTL) and serves cached responses directly until the TTL expires.

| Endpoint                          | Cached | Notes                                       |
| --------------------------------- | ------ | ------------------------------------------- |
| `/block/{shard}/by-nonce/{nonce}` | Yes    | Finalized blocks are immutable              |
| `/block/{shard}/by-hash/{hash}`   | Yes    | Hash-keyed, immutable                       |
| `/hyperblock/by-hash/{hash}`      | Yes    | Hash-keyed, immutable                       |
| `/hyperblock/by-nonce/{nonce}`    | Yes    | Nonce-keyed, immutable after finalization   |
| `/node/heartbeatstatus`           | Yes    | Aggregated heartbeat refreshes periodically |
| `/validator/statistics`           | Yes    | Statistics update once per epoch            |
| `/network/economics`              | Yes    | Refreshes periodically                      |
| Account endpoints                 | No     | Fetched fresh from observer                 |
| Transaction endpoints             | No     | Status changes frequently                   |
| VM query endpoints                | No     | Results depend on current state             |

Block and hyperblock responses are safe to cache indefinitely on the client side once finalized. Use the block nonce or hash as a cache key.

## In-flight request deduplication

When multiple clients request the same data at once, the Gateway sends one request to the observer. Subsequent identical requests wait for that response and receive the same result.

This "leader-follower" pattern (coalescing) prevents thundering herd problems. The first request becomes the leader and contacts the observer. All other requests with the same path and query parameters become followers and wait for the leader's response.

Each coalesced group resolves as soon as the leader receives a response. Followers add no additional latency beyond the leader's round-trip time.

Deduplication applies to all GET requests with identical path and query parameters.

Deduplication is automatic and requires no configuration. This is useful for high-traffic endpoints like account balances where many clients poll the same address.

## Forcing fresh data

To bypass cached data and query the latest state, use these query parameters:

| Parameter             | Effect                                                              |
| --------------------- | ------------------------------------------------------------------- |
| `?onFinalBlock=true`  | Query against the latest finalized block (bypasses any stale cache) |
| `?blockNonce={nonce}` | Query at a specific block height                                    |
| `?blockHash={hash}`   | Query at a specific block hash                                      |

These parameters force the Gateway to contact the observer directly, skipping the cache layer.

```bash theme={"system"}
# Get the latest finalized balance, bypassing cache
curl "https://rust-gateway.xoxno.com/address/erd1.../balance?onFinalBlock=true"

# Query state at a specific block height
curl "https://rust-gateway.xoxno.com/address/erd1.../balance?blockNonce=12345678"
```

## Data availability modes

The Gateway classifies queries into two availability modes based on the parameters you provide:

* **Recent:** any observer can serve these queries, including snapshotless nodes. More observers are available, which means faster responses and better load distribution.
* **All:** only observers with complete history can serve these queries. Fewer observers qualify, but they support historical lookups at arbitrary block heights.

When you include `blockNonce`, `blockHash`, or `onStartOfEpoch` parameters, the Gateway switches to "All" mode and skips snapshotless observers. The Gateway infers the mode from the query parameters.

If you only need current state, omit historical parameters. The Gateway will use the larger pool of "Recent" observers, giving you faster responses.