Imagine: your NFT tracker only shows a static JPEG, but users want to see how the floor price went from 0.05 to 12 ETH in three weeks. Without price history, any tracker is just a catalog. We turn it into an analytics tool in 2–4 days using proven APIs and caching. Reservoir API handles up to 10 times more data than OpenSea on the free tier, and caching reduces load by 70%.
We are a mobile development team with five years of experience and 20+ completed NFT projects. Our architecture sustains 600 requests per minute without data loss. Average API response time is 200 ms, ensuring smooth charts. On a recent project, we integrated history for a collectibles app, reducing API calls by 70% and maintaining 200ms response time even under peak load. Contact us to get your analytic tool in 2–4 days.
Why Price History Is Critical
Price dynamics build user trust. If you don't show how a token's price changed over a week or month, your app loses to competitors. Without history, you can't analyze trends, identify optimal selling points, or assess collection liquidity. Moreover, historical data is essential for automating trading strategies.
How APIs Handle Historical Data
The blockchain doesn't store price history as a separate entity. Each sale is a Transfer event in an ERC-721 smart contract plus an ETH transfer. To build price history, we aggregate on-chain events. We use three approaches:
| API | History Depth | Rate Limit | Marketplaces |
|---|---|---|---|
| Reservoir API | Unlimited | 10 req/sec | OpenSea, Blur, X2Y2, and others |
| OpenSea API v2 | 30 days free | 4 req/sec | OpenSea |
| Alchemy NFT API | Unlimited | 10 req/sec | OpenSea, LooksRare |
Reservoir gives the deepest history and works without pagination but requires an API key. OpenSea is suitable for a quick prototype, but beyond 30 days you need a paid plan. Alchemy is convenient if you already use it for other queries.
Where Price History Comes From
Price history is built from Transfer events and transaction logs. ERC-721 smart contracts emit a Transfer event with from, to, and tokenId. The value is attached from the main transaction — it's the price in wei. According to the ERC-721 specification, the event includes three indexed parameters.
Typical Flutter repository:
class NftSalesRepository { final Dio _dio; final String _reservoirKey; Future<List<NftSale>> getSalesHistory({ required String contractAddress, required String tokenId, DateTime? from, }) async { final params = { 'tokens': '$contractAddress:$tokenId', 'startTimestamp': from?.millisecondsSinceEpoch ~/ 1000, 'limit': 100, }; final resp = await _dio.get( 'https://api.reservoir.tools/sales/v6', queryParameters: params, options: Options(headers: {'x-api-key': _reservoirKey}), ); return (resp.data['sales'] as List) .map((e) => NftSale.fromJson(e)) .toList(); } } The price comes in ETH, but users expect USD. We pull the rate via CoinGecko API, cache it for 60 seconds, and apply it to each point. This guarantees accuracy without extra requests.
Caching: Reduces Load by 70%
Caching is key to performance. We use SQLite with drift (Flutter) or Room (Android) libraries. Data is stored with a TTL of 60 seconds for prices and 300 seconds for metadata. This reduces API queries by 70% and ensures operation on weak connections.
| Strategy | TTL | Application |
|---|---|---|
| Sales data | 60 sec | Price charts |
| Images | 300 sec | NFT cards |
| ETH/USD rate | 60 sec | Conversion |
Technical caching details
We use SQLite with drift (Flutter) or Room (Android). TTL is set individually: 60 seconds for prices, 300 seconds for metadata. When offline, data loads from cache, ensuring stable functionality.What's Included
- API integration: Reservoir, OpenSea, or Alchemy with full pagination and error handling.
- Data models: NftSale, PricePoint with wei → ETH → USD conversion.
- Caching: SQLite (drift/floor) with TTL for data and images, with force refresh option.
- Chart: time range selection (7d / 30d / All), smoothing, outlier filtering.
- Error handling: empty history, network errors, API limits — all with a clear UI.
Process
- Analysis: Review your stack and design mockups. Determine which data is needed and how often it updates.
-
Design: Choose API, caching schema, query architecture (e.g., using
GetItfor DI). - Implementation: Integrate API, render chart, handle wash-trade (filter sales between related wallets via cluster analysis).
- Testing: Unit tests for repositories, widget tests for chart, load testing up to 600 requests per minute.
- Deploy: Publish to App Store / Google Play, set up push notifications for large price changes.
Timeline Estimate
Basic integration with the chart takes 2 to 4 working days. Complexity affects duration: additional filters, custom contracts, or non-standard design may increase time. Pricing is determined individually after analyzing your requirements.
Common Mistakes and Solutions
-
Incorrect time conversion: Blockchain timestamps are in seconds, not milliseconds — this shifts the graph to 1970. We use
DateTime.fromMillisecondsSinceEpoch(timestamp * 1000). - Wash-trading: Sales between same-owner wallets distort median price. We apply cluster analysis on on-chain connections and exclude such transactions.
- Stale data: If cache isn't refreshed, users see prices from hours ago. TTL of 60 seconds is the sweet spot.
Contact us to discuss your project and get a tailored proposal. We guarantee stable performance under load and transparent architecture.