Why DeBank API integration hits limits and duplicates
A wallet portfolio is tokens on the balance, deposited positions in protocols, staking, and loan debts. To assemble this on one screen, the frontend queries DeBank for each address.
On a stream of tens of thousands of wallets, the external service begins responding with failures or returning an incomplete response.
The first bottleneck is request limits. While there are few addresses, the scheduled traversal completes in full; as load grows, some addresses are not updated, and the frontend shows stale balances. The user sees an amount that is no longer on the address and makes decisions based on it.
Second — duplicate operations. A repeated query after a connection drop, a restart of a stuck task, or two parallel updates of the same address produce doubled positions: the same deposit is counted twice.
This is solved not by retrying the request, but by an idempotent write with a key by address, protocol, and position ID.
Third — external service errors: brief failures and partial responses. If the frontend goes to the external source on every page view, a delay on the service side becomes a delay for the user, and the load on the frontend grows with the number of open screens.
Therefore, responses are cached by address and time window, and incomplete data is returned with an explicit mark until the next successful update.
We discuss how this is addressed: a queue that accounts for allocated quotas, deduplication on writes, and a cache layer between the frontend and the external service.
What a unified data layer for a DeFi portfolio provides
A unified data layer is an intermediary between the frontend and external sources: balance aggregation goes through the DeBank API DeBank, and the frontend reads the already assembled DeFi portfolio from our storage.
The application stops depending on someone else's load: we show the last known snapshot and update it in the background, instead of waiting for a response for each address at render time.
Data freshness is set by a schedule, not by guesswork: addresses with frequent visits are updated more often, archived ones less often, and rare positions are loaded on demand.
This mode keeps the frontend response steady and removes most requests from the external service — at peak, there are an order of magnitude fewer than with direct calls.
| Option | When it fits | Limitations |
|---|---|---|
| Direct call to the external API on every view | One-off audit, single addresses | Frontend response depends on external load; request limits; if the service is unavailable, the section is empty |
| Own cache with background updates | Regular users, frequent views of the same addresses | Requires a scheduler and event-based record invalidation; data lags by the update interval |
| Cache plus on-demand loading | Long portfolios, new addresses, rare assets | More complex priority and partial response merging logic |
| Own indexers by nodes | Non-standard metrics and full control over data | Node maintenance, indexing delay, higher cost of ownership |
The output is verifiable numbers: balance freshness stays within the update interval, the share of successful frontend responses remains above 99%, and response time does not grow during traffic spikes.
Some addresses are served from cache immediately, so the portfolio section opens equally fast during quiet hours and at peak.
Data retrieval modes: comparison of approaches
The data retrieval mode is chosen by two parameters: how often the address state changes and how many addresses are in the portfolio at the same time.
The DeBank API returns balances and transaction history, but each request consumes the request limit — direct polling for each wallet quickly becomes both the most expensive and the most fragile path.
| Option | When it fits | Limitations |
|---|---|---|
| Direct polling | Single addresses, debugging, manual checks | Number of requests grows linearly, and with it response time |
| Scheduled cache | Portfolio overview, updates every few minutes | Data lags behind the network; a frequent schedule hits the limit |
| Event stream | Transfers and trades close to real time | Requires a stable subscription and handling of gaps after a disconnect |
| Own index | Analytics, historical slices, yield calculation | Own storage, recalculation, and synchronization with the network |
Hybrid scheme
The hybrid scheme assembles a working combination: hot addresses are updated by the event stream, the rest by the scheduled cache, rare point queries go to direct polling, and historical slices are calculated by the own index.
The boundaries between modes are set by a threshold on the number of addresses and the frequency of changes — portfolio response remains predictable, and limit consumption does not grow with the database.
Implementation stages: from call audit to handover
The work proceeds sequentially: until the composition of calls is described, there is no basis for configuring the cache and retries, and without observability it is impossible to prove that the integration will survive peak load. Each stage ends with a verifiable result that can be compared with the baseline measurement.
- Call audit. We inventory which DeBank API methods are already used, at what frequency, how many requests are duplicated, and where we hit rate limits. The output is a call map with priorities and an explicit list of requests that are not needed at all.
- Data schema. We bring responses to a unified model: networks and assets, positions in protocols, value, transaction history. We fix the rules by which duplicates are merged and what we do with assets that the source did not return.
- Cache setup. We split data by staleness rate: balances and positions are cached briefly, token directories and rates longer, history on demand. We separately describe cache warming for the expected load profile.
- Retries on failures. We introduce a limit on parallel requests, retry with increasing delay, and a distinction: what we retry automatically and what we send to the queue. Errors of one wallet must not block processing of the others.
- Observability. We output metrics: share of responses from cache, response time, error rate by method, queue depth. From them it is clear where the bottleneck is — this is the basis for handover without guesswork.
- Verification on real wallets. We compare the portfolio with a reference calculation and run edge cases: empty wallet, dozens of networks, assets without a rate.
- Handover. We hand over configurations, the data schema, limit instructions, and metric analysis — the client's team then changes parameters itself.
Configurations, data schemas, and operating regulations
After implementation, the client retains not only a working service but also a set of artifacts: settings, a data schema description, access rules, retry and degradation regulations.
Below is the full list of what we hand over to the team so that it can change the behavior of the DeBank API integration without digging into the code.
- Configuration. A single settings file: request limits, caching windows for each data type, timeouts, degradation thresholds. Each parameter has a comment with a safe range and the consequence of going beyond it.
- Data schema description. A field mapping table: what goes into the models of address, portfolio, balances, and positions in protocols, how addresses and token precision are normalized, what we consider a zero balance.
- Access policies. Separate keys for reading and for service operations, roles in the secret storage, and a rotation procedure without stopping the service.
- Retry regulations. Exponential backoff with jitter, a limit on concurrent requests, and a distinction between retryable and non-retryable errors: the latter go to an on-call notification rather than into a loop.
- Degradation. When the limit is exhausted, we return the last successful snapshot with a timestamp — the interface shows the age of the data instead of an empty screen.
- Documentation. On-call instructions: key reissue, cache warming after a failure, configuration rollback, an acceptance checklist with reproducible scenarios.
The package lives together with the service: changes in the response schema and limits are recorded in the documentation before release, so the regulations do not diverge from the actual behavior of the system.
Case study: a DeFi portfolio frontend on a stream of wallets
The frontend assembles portfolios from a stream of wallets: the user enters an address and gets balances, positions in protocols, and value in a single currency.
We pull data from the DeBank API — one request returns the entire portfolio, but the request rate is limited, and with tens of thousands of addresses this became a bottleneck.
Before
Every page view went to the source again, and repeated updates did not reuse already received data.
At peak, the frontend hit the request limit: the share of successful responses remained around 70%, response time reached 8–12 seconds, and for some addresses balances diverged from protocol data — the figure on the screen did not match the wallet.
What we did
We introduced a cache by the key “address + network” with different lifetimes for fast and stable data: token balances live for minutes, positions in pools for tens of seconds.
A background traversal warms the cache in advance, so the frontend responds without waiting for the source.
Repeated requests were smoothed by a rate-limited queue, batching addresses, and retries with increasing delay. We verify balances in two passes: if the discrepancy is above the threshold, we show the last confirmed value rather than an intermediate one.
What changed
The share of successful responses grew from 70% to 99.3%, and repeated calls decreased by a factor of 6 — the cache absorbs them.
The frontend response dropped from 8–12 seconds to 0.4–0.8 seconds on a cache hit, and balance discrepancies decreased to isolated cases per day: each is investigated using the reconciliation log.
How direct polling of DeBank API differs from your own cache
Direct polling of the DeBank API returns the portfolio state at the time of the request: balances by network, positions in protocols, valuation in the base currency.
While there are few addresses and requests are single, this is the shortest path — there is no own database, nothing to synchronize, and the data is guaranteed fresh.
Limitations appear at scale: the service has a rate limit, and a screen with dozens of wallets hits response time and failures under peak load.
An intermediate layer removes this: addresses are polled on a schedule, the result is stored in your own database, and the interface reads it. Predictable response time and change history appear — you can show portfolio dynamics, not just the current snapshot.
The price for this is consistency: you need to decide what to do with a discrepancy between the cache and a fresh response, how to mark stale records, and when to force a refetch.
A separate cost item is maintenance effort: response schemas change, networks and protocols are added, storage volumes grow, and retries on failures and control of stuck update tasks are needed.
The hybrid scheme usually turns out to be the working one: we take hot data for active addresses directly, the rest from the cache according to the update regulations, and we recheck values that affect calculations before displaying them.
The choice between modes rests on three questions: how many addresses are on the screen at the same time, whether history is needed, and how critical a discrepancy with the source is. The answers to them determine the architecture.
Technical doubts we resolve before starting
Before starting integration, technical doubts are usually more important than portfolio collection itself: the client needs to understand what will happen when the external service starts returning incomplete data or hits limits.
Below are the questions we work through with the engineering team before the first line of code, so that the design does not require rework in production.
We wrap calls to DeBank in our own access layer. It groups requests by address in one pass, distributes them over time with headroom to the limits, and returns the last valid version from the cache while the freshness window has not expired.
We store balance history in our own database — it is not lost when the provider has a failure and allows recalculating the portfolio value for any date.
What will the user see if the external service goes down or cuts limits?
The interface returns data marked as coming from the cache with the last update time, rather than an empty screen. Retries proceed with increasing delay, some requests go to the queue and are loaded when the limit frees up. An external service error does not turn into an error of our product.
How are balances recalculated when the asset composition changes?
Recalculation is triggered by an event: new address transactions, a change in the token set, a scheduled price update. We calculate not “on the fly” on every page open, but by schedule and by trigger — this removes load and gives the same result when the portfolio is reopened.
How long is history stored and can it be rebuilt?
We store raw provider responses separately from aggregates: if the calculation methodology changes, history can be rebuilt without re-querying the external service. We set the storage depth at the start — the database size and the speed of long-period reports depend on it.
How well are API access keys protected?
Keys do not get into code, the frontend, or logs: they are stored in a secure vault, read only by the service layer, and issued via short-lived tokens. Key rotation does not require an application rollout, and every call is written to a log with sensitive fields masked.
Let's discuss the task: we'll review the design and come back with an estimate
To come back with an accurate estimate of the scope of work, rather than a “plus or minus” range, we need input: how the data is structured, which networks and protocols are in use, where transaction history comes from, and whether there is already an address database. The fuller the picture, the fewer assumptions in the implementation plan.
What we request at the start:
- List of networks and protocols for the portfolio — we check the source coverage and decide where a custom data collector is needed.
- Test access and confirmed request limits — the caching scheme and balance recalculation frequency depend on them.
- 3–5 addresses with the expected result — we use them to check response parsing and value conversion rules.
- Where balances, history, and snapshots currently reside and how often they are updated.
- Requirements for data freshness and behavior when the source is unavailable.
- Target interfaces — dashboard, report, external system: the output format and aggregation depend on them.
We come back with an integration design, a list of failure points, and the stages of an implementation plan, where each step has its own scope estimate. We keep the DeBank API as one of the sources: where its data is sufficient, we do not duplicate with our own indexer.
We suggest discussing the task — describe the inputs, and we will come back with an estimate and a plan.