Cache Keys for Blockchain API Responses
Build cache keys from network, method, asset, wallet and state context, and avoid serving latest-state results for historical or differently authorised queries.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A cache is correct only when its key captures the distinctions that affect the result. Wallet address alone is rarely enough for a blockchain data response.
Include semantic inputs
Use network identity, method, normalised parameters and relevant block or range context. Include tenant or authorisation scope when results differ by caller. A hash-pinned historical read and a latest-state read need different freshness policies. Do not store API secrets directly in visible cache keys or logs.
Worked example: a historical request hits latest
The cache stores a wallet’s latest token balance under wallet-plus-contract. A later request asks for the balance at block 100 and receives that cached latest value. Adding the state reference to the key prevents the collision. It also allows immutable historical evidence and moving-head responses to use different expiry policies.
Test invalidation and isolation
Include a chain switch, changed permissions, metadata corrections and a reorganisation affecting provisional results. Cache errors only under a deliberate short-lived policy, if at all. A missing price cached as zero can contaminate many valuations. Preserve the response context so callers can verify what the cached result actually represents.
A practical acceptance test
Cache the same wallet and token on two networks and at two state references. Assert four distinct query contexts where needed. Add a private label visible only to one tenant and verify that another tenant cannot retrieve the enriched response. Cache expiry and correction invalidation should be tested separately from key uniqueness.
Questions about the topic
Frequently asked questions
Is wallet address a sufficient cache key?
No. Network, query and state context usually matter.
Can historical and latest reads share one expiry rule?
They can have different semantics and should be evaluated separately.
Standards & technical documentation
