Dune Analytics API: Where Data Export into a Product Breaks
Dune Analytics API is integrated when a product needs on-chain metrics without its own indexer: wallet balances, pool volumes, contract activity.
The external service has already collected data and arranged it into marts; a query returns a ready result, and the product renders it in the interface. The simplicity is deceptive — what follows is operating someone else's mart with its own rebuild schedule.
The first typical failure is a stale mart. Materialized views are updated on schedule, and between rebuilds the service returns a snapshot for the previous period.
The query is formally successful, while the user sees data lag in the interface and interprets it as a product failure.
The second is balance discrepancy. The accounting sum in the mart almost always differs from the actual network state: some transfers have not yet made it into the rebuild, some are awaiting confirmations.
On a wallet screen or in a report, this reads as an error, although the source returned exactly what it had at the time of extraction.
The third is request limits. The request pool is shared, a load spike returns a rejection, and the refresh fails silently: the interface calmly continues showing yesterday's numbers because no one raised the error.
We'll break down how this is addressed — freshness control, reconciliation with network state, retries, and explicit degradation instead of an empty or false screen.
What Built-in Access to Blockchain Data Gives a Product
Built-in access to Dune Analytics removes the layer that makes product reporting always lag behind the network: queries go directly to the data, and the client sees the balance, transaction history, or wallet activity in the same slice as the analyst.
Freshness is measured in block confirmation minutes, not days since export, and the refresh frequency is configurable — hot metrics update more often, historical ones on schedule, so as not to hit the external service's limits.
A single source of truth changes not the picture but the process. Metrics in the interface, exports for finance, and internal dashboards are calculated by the same query, so discrepancies do not accumulate between systems.
Manual reconciliations are reduced to spot checks: the mismatch is caught by the query itself, not by a person a week after the export.
The class of failures "data failed to load" is addressed separately.
A request queue with retries and increasing delay, a cache of the last successful response, and explicit marking of stale values prevent the interface from showing an empty balance instead of the real one.
If the external source is unavailable, the product continues to work on the last snapshot and loads the missing part itself — recovery time after a failure is measured in minutes, not hours waiting for support to respond.
Integration Formats: Own Indexer, Ready-Made API, Exports
The access format for on-chain data is chosen by three parameters: query history depth, acceptable delay between an event on the network and a row in your database, and how critical this data is to product logic.
A mistake here costs more than the integration itself — the data layer gets rewritten together with reporting and accruals.
Below are four schemes that teams actually choose between, and the applicable boundaries of each. Most often the hybrid wins: historical slices are taken from a ready-made data service, and fresh events are calculated locally.
| Option | When It Fits | Limitations |
|---|---|---|
| Own indexer | Custom block parsing rules, private metrics, data outside public datasets | History only from launch; rollbacks, reindexing, and contract changes are maintained by you |
| Ready-made data service (Dune Analytics API) | You need history from the first blocks and parsing of popular protocols without your own infrastructure | Dependence on someone else's update schedule and limits; rare contracts are sometimes unlabeled |
| Regular exports | Reporting and analytics where data is needed once an hour or less often | Delay until it appears in your database; if an export fails, the window is lost, and gap control is needed |
| Hybrid scheme | You need both deep history and fresh events with low latency | More expensive to maintain: sources are reconciled, metric divergence is monitored |
Query History Depth
This is the decisive criterion. If the product operates on events from the last few days, an own indexer pays off faster and does not create external dependencies.
If you need multi-year slices and parsing of third-party protocols, a ready-made mart solves the task immediately, while the local layer is kept only for the fresh stream.
Workflow: From Query Audit to Schema Handover
We start not with code but with an inventory: every query must have a clear consumer and owner. Then we fix the flow schema and only after that touch accesses and formats — this way, changing one query does not break a dashboard or mart that knows nothing about it.
- Query and consumer audit. We compile a list of queries in Dune, note who reads the result: monitoring dashboard, mart, service, or regular export. We mark duplicates, abandoned queries, and those with no owner.
- Data flow schema. We draw the path from query to consumer, with an intermediate storage point, transformation location, and acceptable refresh delay. We fix the contract: field names and types, rounding rules, behavior on an empty response.
- Keys and access rights. A separate key for each environment and service, minimally necessary permissions, storage in a secret vault, and rotation. We describe behavior when the external service's request limit is exhausted.
- Bringing data to a unified form. Unified network and token identifiers, normalization of addresses and decimal values, handling of chain reorganizations. A metric stops depending on which query produced it.
- Reconciliation check. We compare totals with an independent source on a control sample of periods, cross-check sums and the number of unique addresses. We investigate discrepancies to the cause, not to an acceptable range.
- Handover and training. Documentation for each query, flow schema, procedures for divergence and external service failure, review with the team.
At the end, the team edits queries itself, adds metrics, and sees exactly where the numbers diverged.
Query Schemas, Access Keys, and Refresh Policies
Work with the Dune Analytics API does not end when queries start returning data. If the descriptions live only in the developer's head, the first contract change breaks reporting — so we hand over a package that the client's team can use independently.
Below is the required composition of such a package. We check each item at acceptance: without it, the work is not considered complete.
- Query schemas — purpose, fields, and relationships between tables, filters by addresses and periods, example of the expected result for reconciliation.
- Connection configurations — access keys, request limits, environment variables, separate settings for development and production environments.
- Role-based access policies — who sees raw data, who sees only aggregates, who is allowed to change queries; key lifetime and issuance log.
- Refresh policy — what to do when contract addresses change, interface descriptions are edited, or blocks are rebuilt, who is responsible for reconciliation and how often.
- Team instructions — how to bring up the environment, run a query, check data freshness, and where to look when there is a discrepancy.
- Versions and rollback — a log of edits with date and reason, ability to restore the previous query version without stopping reporting.
- Control checks — points by which we reconcile data before and after any contract changes.
Case Study: Data Delay Reduced from Hours to Minutes
The client is a product with analytics for blockchain networks: dashboards showed address activity, pool volumes, and fund movements.
Data was pulled by batch exports on a schedule, so the mart updated once every few hours, and discrepancies with the source were investigated manually. Reconciliation took up to half of the analyst's working time.
What Was Changed
We switched data retrieval to requests to the Dune Analytics API at the moment the dashboard opens, and added a cache with different lifetimes for "hot" and historical metrics.
Queries went into a queue with limited concurrency and retries on temporary errors — the source stopped receiving peak spikes. The response schema was fixed by contract, so changes on the service side no longer broke the mart.
What Was Achieved
Data freshness improved from hours to 1-3 minutes, and the share of manual reconciliations dropped almost to zero — discrepancies are now caught by an automatic control-value check.
We closed the failure class "stale snapshot": previously, the user saw figures as of the previous export and made decisions based on them. The mart's response time did not increase because heavy queries are calculated in advance rather than at display time.
The implementation took several weeks: migrating the logic, testing on historical data, gradually enabling sections one by one.
The load on the product remained the same — request frequency increased, but the volume of transmitted data decreased by selecting only the required fields.
How a Ready-Made Data Service Differs from Your Own Indexing
A ready-made service like Dune Analytics returns data via an API request over an already built index.
As long as the task fits standard contracts and standard events — tokens, transfers, trades on major exchanges — starting takes days: no need to bring up a node, write parsers, and wait for the chain to index up to the required block.
The fork begins where data completeness is needed. An external index contains only what its authors decided to collect: a custom contract with non-standard event logic, a rare network, or logs before a certain block will not make it into the dataset. There is nothing external to supplement it with — you have to index it yourself.
Accuracy is the second constraint. Recalculation after the fact changes past aggregates, and the moment of block finality is not under our control: the service decides for itself when the figure has settled.
If a product calculates balances, limits, or payouts, a one-block discrepancy turns into an incident requiring investigation.
Privacy closes the question for some scenarios. Client addresses, internal wallet labeling, and commercial volumes should not leave the perimeter — such an index is built only in-house, and an external service is fundamentally unsuitable here.
Maintenance effort is the price of independence: an archive node, reindexing when contracts update, lag monitoring, reorganization handling, schema migration.
That is why the choice is not made on an either-or basis: standard metrics are taken from a ready-made service, while unique logic and private data are collected into your own mart.
Common Technical Doubts Before Starting Integration
Most often, before starting, people ask not about capabilities but about integration with what already works: will the figures match their own analytics, who is responsible for changing queries, and how to separate access.
These doubts are resolved at the design stage, and it is cheaper to close them before the first line of product code. Below is a breakdown of the applicability conditions that determine the scope of work.
Will the data diverge from our current reporting?
The on-chain layer is connected as a separate source and does not rewrite the existing storage.
Matching is done by stable keys — address, transaction hash, block number: on historical slices, we reconcile aggregates, and eliminate discrepancies before outputting metrics to the interface.
Any residual difference in units and time zones is recorded in the field description so that the figures read the same.
What happens if external queries change or break?
Queries are stored in a repository and versioned, rather than living in someone's personal account. On top, we add anomaly checks: empty result, metric drop to zero, interval skip — they raise a notification before the data goes into the product. When the external schema changes, we edit the query layer and do not touch the product logic.
How to limit access, and when is integration not needed at all?
We move keys to a secret vault, separate them by roles and read scopes, and log requests. If the task is one metric once a day, a scheduled export is sufficient.
A dedicated access layer is justified when you need historical slices, derived calculations, and a metric within a user scenario.
Let's Discuss the Task: What Data Is Needed for an Accurate Estimate
For the estimate to be accurate rather than "plus or minus", we need inputs — not a general description, but specifics about the data. The list of networks and contract addresses you are interested in determines the volume of datasets and how indexing is built. You can send the data in any form: a table, a list of addresses, screenshots of current dashboards.
It would be useful to receive from you:
- a list of networks and contracts for which metrics are needed;
- a list of data consumers: dashboard, internal service, reporting for partners;
- current export methods — manual export, node queries, ready-made dashboards, calls to the Dune Analytics API;
- freshness requirements: real time, once an hour, or once a day — the refresh scheme depends on this;
- roles and access: who sees raw data, who sees only aggregates;
- expected output format — table, event, metric in the interface;
- constraints on load and fault tolerance, if the service is already running under load.
Based on these inputs, we will describe the work plan: which contracts we traverse, what storage model is needed, where we place the cache, and how we handle gaps in blocks.
We fix acceptance criteria before the start — reconciliation of aggregates with an independent source, behavior during reindexing, and completeness of historical data for the required period.
Describe the task — we will come back with an estimate, a work plan, and timelines by stage.