feat(token-aggregation): add historical pricing context, backfill, and indexer hardening

services/token-aggregation/docs/REST_API_REFERENCE.md

@@ -177,6 +177,39 @@ OHLCV (candlestick) data for charts.
 
 **Response:** `{ chainId, tokenAddress, interval, data: OHLCV[] }`
 
+### GET /api/v1/tokens/:address/price-at
+
+Point-in-time USD valuation for a token at or immediately before a requested timestamp. Intended for explorer transaction detail pages where the transfer-time value should stay anchored to the transaction, while wallet/address/token overview pages can continue showing current market value.
+
+**Query:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| chainId | number | yes | 138 or 651940 |
+| timestamp | ISO date | yes | Transfer time to price against |
+
+**Response:** `{ chainId, tokenAddress, requestedTimestamp, effectiveTimestamp?, priceUsd?, source }`
+
+- `source` is one of `swap_event`, `ohlcv_5m`, `ohlcv_15m`, `ohlcv_1h`, `ohlcv_4h`, `ohlcv_24h`, `current_market_fallback`, `canonical_fallback`, or `unavailable`
+- `effectiveTimestamp` is the candle/snapshot time actually used for valuation
+
+### GET /api/v1/tokens/:address/pricing-context
+
+Snap-ready combined pricing response for one token. Returns the current market valuation and, when `timestamp` is supplied, a transfer-time historical valuation in the same payload.
+
+**Query:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| chainId | number | yes | 138 or 651940 |
+| timestamp | ISO date | no | Transfer time to price against |
+
+**Response:** `{ chainId, tokenAddress, current, historical? }`
+
+- `current` includes `{ chainId, tokenAddress, priceUsd?, asOf?, sourceLayer, stale, marketLastUpdated? }`
+- `historical` includes `{ chainId, tokenAddress, requestedTimestamp, effectiveTimestamp?, priceUsd?, source, locked }`
+- `locked` is `true` only when the historical price came from `swap_event` or an `ohlcv_*` source; fallback values are returned with `locked: false`
+
 ### GET /api/v1/tokens/:address/signals
 
 Trending/signals (e.g. CoinGecko trending rank) for a token.