Data Freshness

Understanding how often data updates helps you build better applications.

Cache TTL by Data Type

Data Type	Cache TTL	Update Frequency	Notes
Token Prices	30 seconds	Real-time	From CoinGecko/DefiLlama
Gas Prices	15 seconds	Per block	~12s on Ethereum
ENS Resolution	5 minutes	On-chain events	Cached after first lookup
ENS Profiles	1 hour	Rare changes	Avatar, bio, records
Farcaster Profiles	5 minutes	User updates	Follower counts may lag
Farcaster Feeds	2 minutes	Continuous	New casts every few seconds
Farcaster Channels	10 minutes	Variable	Channel stats
DeFi TVL	5 minutes	Hourly+	From DefiLlama
Protocol Yields	15 minutes	Variable	APY calculations
Staking Data	10 minutes	Variable	Validator stats
Wallet Balances	1 minute	Per block	May lag during congestion
Token Holdings	2 minutes	Per block	ERC-20 balances
NFT Holdings	5 minutes	On transfer	Ownership changes
NFT Metadata	24 hours	Rare changes	IPFS content immutable
Security Scans	30 minutes	On-demand	Token contract analysis
Fear & Greed Index	1 hour	Daily update	Sentiment indicator
Historical Data	Indefinite	Never	Past data is immutable

Response Headers

Every response includes cache information:

X-Cache-TTL: 30
X-Cache-Hit: true
X-Data-Timestamp: 2026-02-08T12:00:00Z

Header	Description
X-Cache-TTL	Seconds until data is considered stale
X-Cache-Hit	Whether response came from cache
X-Data-Timestamp	When the data was last fetched from source

Freshness Guarantees

Real-Time Data (< 1 minute)

Best for: Trading apps, gas estimation, price alerts

# Token prices - 30s cache
curl https://api.web3identity.com/api/price/eth

# Gas prices - 15s cache
curl https://api.web3identity.com/api/gas

Near Real-Time (1-5 minutes)

Best for: Wallet apps, social features, dashboards

# Wallet balances - 1m cache
curl https://api.web3identity.com/api/wallet/0x.../balances

# ENS resolution - 5m cache
curl https://api.web3identity.com/api/ens/resolve/vitalik.eth

Periodic Updates (5-60 minutes)

Best for: Analytics, leaderboards, aggregate stats

# DeFi TVL - 5m cache
curl https://api.web3identity.com/api/defi/tvl

# Protocol yields - 15m cache
curl https://api.web3identity.com/api/yields

Static Data (hours to days)

Best for: Profile pages, NFT displays, historical analysis

# ENS full profile - 1h cache
curl https://api.web3identity.com/api/ens/profile/vitalik.eth

# NFT metadata - 24h cache
curl https://api.web3identity.com/api/nft/0x.../1

Force Fresh Data

For critical operations, you can bypass the cache:

curl -H "Cache-Control: no-cache" \
  https://api.web3identity.com/api/price/eth

Rate Limit Impact

Cache bypass requests count against your rate limit. Use sparingly.

Best Practices

Match TTL to Use Case

// ✅ Good: Cache matches data volatility
const priceCache = new Map(); // 30s TTL
const profileCache = new Map(); // 1h TTL

// ❌ Bad: Same cache for everything
const cache = new Map(); // 5m TTL for all

Stale-While-Revalidate

Serve cached data immediately, refresh in background:

async function getPrice(token) {
  const cached = priceCache.get(token);
  const now = Date.now();
  
  // Fresh enough - return immediately
  if (cached && now - cached.time < 30000) {
    return cached.data;
  }
  
  // Stale but usable - return and refresh
  if (cached && now - cached.time < 60000) {
    refreshPrice(token); // Background refresh
    return cached.data;
  }
  
  // Too stale - must wait for fresh data
  return await fetchPrice(token);
}

Handle Stale Data Gracefully

const data = await api.getPrice('eth');
const age = Date.now() - new Date(data.timestamp).getTime();

if (age > 60000) {
  // Data is over 1 minute old
  showWarning('Price may be outdated');
}

Data Source Latency

Different sources have different update frequencies:

Source	Typical Latency	Notes
Direct RPC	1-2 blocks	Most accurate
The Graph	1-5 minutes	Indexed data
CoinGecko	30-60 seconds	Price aggregation
DefiLlama	5-15 minutes	TVL calculations
Neynar (Farcaster)	Near real-time	Social data

Monitoring Freshness

Check data source health:

curl https://api.web3identity.com/api/sources/health

{
  "sources": {
    "coingecko": { "status": "healthy", "lastUpdate": "2026-02-08T12:00:00Z" },
    "defillama": { "status": "healthy", "lastUpdate": "2026-02-08T11:55:00Z" },
    "neynar": { "status": "healthy", "lastUpdate": "2026-02-08T12:00:05Z" }
  }
}