Etherscan limits are request Caps That Shape Reliable API Calls

Etherscan limits are plan-based API request caps that govern calls per second and per day, with certain data-heavy endpoints held to 2 calls per second regardless of a higher paid tier. A client avoids rate errors by placing every request for the same API key behind one limiter, reserving capacity before sending work and retrying rejected calls with backoff plus jitter. Daily quotas matter as much as burst control because pagination, ERC-20 transfers and multichain polling multiply request counts quickly. This guide focuses on the engineering slice: calculate a budget, separate endpoint ceilings, queue Ethereum and other EVM-chain jobs, cache repeat reads and measure remaining headroom before traffic reaches the cap.

Key takeaway: They are API request caps that throttle calls by plan and endpoint, with historical data endpoints restricted to two calls per second.

Budgeting One Multichain Request Flow

A stable Etherscan request flow budgets the complete user action before any worker sends its first call.

A portfolio refresh for Ethereum, Base and Arbitrum One already creates three network jobs because API V2 accepts one chainid per request. Add normal transactions, internal transactions and ERC-20 transfers, and each address produces several endpoint calls rather than one explorer lookup. The multichain key simplifies authentication; it doesn’t combine those datasets. A client should expand the requested screen into concrete jobs, classify each job by endpoint family and reserve quota before dispatch. That order exposes the true burst before parallel workers hit Etherscan together.

Chain IDs 1, 8453 and 42161 select Ethereum, Base and Arbitrum One. Polygon uses 137, while BNB Smart Chain uses 56. Those identifiers route calls; they don’t create separate rate allowances. Five chain queries remain five metered calls even when one API key authenticates all of them.

Once the workload is explicit, the client can choose between queued explorer reads and a direct JSON-RPC data path for high-frequency state.

Plan Caps Set Both Burst and Daily Capacity

Plan selection sets two independent Etherscan limits: a short request rate and a total daily credit allowance.

Free permits 3 calls per second and 100,000 calls per day. Lite allows 5 per second with the same 100,000-call daily ceiling. Standard moves to 10 per second and 200,000 daily calls, while Advanced permits 20 per second and 500,000 daily calls. Professional reaches 30 per second and 1,000,000 per day. Pro Plus keeps 30 per second but raises the daily allowance to 1,500,000. Standard is also the first tier with API PRO endpoints.

Three calls per second sustained through all 86,400 seconds of a day equals 259,200 calls, so Free reaches its 100,000 daily ceiling first. Its full-day average is about 1.16 calls per second. Standard’s 200,000 credits average about 2.31 calls per second across a day, despite the 10-call burst rate. Capacity planning must satisfy both clocks.

A higher short-term cap solves bursts; a larger daily allowance solves sustained volume.

Historical Endpoints Keep a Separate Two-Call Ceiling

Data-heavy Etherscan endpoints keep a two-calls-per-second ceiling even when the account tier allows much faster community calls.

The stricter group includes historical native balances, historical ERC-20 balances and historical token supply queries. Address-funded-by and address token-holding endpoints also carry the 2-call ceiling. These calls require API PRO access, which starts at Standard, yet a Professional account’s 30-call general rate doesn’t lift their endpoint limit. Route them into a dedicated bucket so ordinary balance or transaction requests can use the wider plan allowance.

A conservative limiter releases one historical request every 500 milliseconds with burst capacity set to 1. When the global bucket permits 30 calls but the endpoint bucket permits 2, the lower ceiling wins. Upgrading expands access and total capacity, not this fixed historical rate.

Pagination Multiplies the Metered Call Count

Pagination controls quota consumption because one logical Etherscan history request becomes several metered API calls as its result set grows.

Free-tier requests to affected transaction, transfer and log endpoints return at most 1,000 records per request. A result containing 1 through 1,000 records fits one page; 1,001 through 2,000 records needs at least 2 pages, and 2,001 through 3,000 needs at least 3. Normal transactions, internal transactions, ERC-20 transfers, ERC-721 transfers and ERC-1155 transfers all belong in the affected group, so a broad address history consumes quota faster than its single screen suggests.

Set offset at or below the endpoint cap and advance page deterministically. Stop when a page returns fewer records than requested. For large histories, split by nonoverlapping block ranges and preserve the chosen ascending or descending sort order. Deduplicate logs by transaction hash plus log index when range boundaries meet.

A narrow contract address and block range usually saves more calls than requesting the full history and filtering locally.

A Shared Queue Prevents Cross-Chain Bursts

One shared queue should enforce Etherscan limits across every process, chain and endpoint using the same API key.

Independent workers can’t see each other’s counters. If five workers each release 3 calls together, the service receives 15 calls in the burst even though every local limiter appears compliant.

One Budget per API Key

The queue should tag each job with an API-key identifier, endpoint class and chain ID before a rate bucket grants permission.

Single-Process Workers

A single server can hold a token bucket in memory, provided all Etherscan calls pass through that process and restarts don’t release a stored backlog at once.

Distributed Workers

Several servers need shared state. Redis supports an atomic bucket, while BullMQ or AWS SQS can hold queued jobs. The queue stores work; the shared counter decides release timing. This design keeps Base and Polygon requests from racing Ethereum jobs under the same key.

Retries Need Backoff, Jitter and Error Classification

Etherscan rate-limit retries work only when the client backs off, adds jitter and separates quota rejection from permanent input errors. The same ground is broken down in Etherscan how wallets work.

A useful starting policy waits 1 second, then 2, 4 and 8 seconds, adding a small random offset to each delay. Cap the attempt count and return the job to the central queue before retrying. Jitter stops synchronized workers from waking together, while exponential growth reduces pressure after repeated rejection. Preserve the original page, block range and sort direction so a retry resumes the same read.

Retry rate-limit and transient timeout responses. Invalid actions, malformed addresses, unsupported chain IDs and invalid credentials need correction instead of another identical request. That boundary keeps recovery traffic smaller than the original burst.

Block-Aware Caching Removes Duplicate Reads

An Etherscan cache cuts request volume by reusing identical responses and coalescing concurrent work for the same query.

Build the cache key from chainid, module, action, address, contract, block range, page and sort order. Omitting one field risks returning Ethereum data for Base or mixing ascending and descending histories. Cache verified implementation ABIs longer than latest balances. An EIP-1967 proxy can point to a new implementation while retaining its proxy address, so key implementation metadata by the resolved implementation address. Request coalescing also matters: ten simultaneous views of one address should await one in-flight call rather than spend ten credits.

Ethereum slots target 12 seconds, so a block-level dashboard gains little from polling unchanged state every second. Other EVM chains need their own block-aware invalidation cadence. A cache that refreshes after the observed block number changes preserves fresher data than an arbitrary timer.

Error Payloads Separate Quotas From Bad Inputs

At a protocol level, Etherscan error payloads reveal whether the caller crossed a quota, sent an invalid parameter or queried an unsupported chain.

An API-level failure uses status value 0, places NOTOK in message and explains the cause in result. A client that checks only the transport status can treat a failed body as usable data. Parse both layers before releasing dependent jobs.

More than 5 invalid API key attempts within a 30-second window trigger a temporary source-IP throttle, which resets after 30 seconds. Correct the credential and wait; exponential retries won’t repair the key. A maximum-rate message belongs in the queue’s retry path. A query-timeout message points to an oversized dataset, so reduce the block or date range before resubmitting.

Body-aware classification separates capacity pressure from query repair, which produces cleaner behavior than treating every non-success response as congestion.

Endpoint Shape Determines the Real Call Volume

Endpoint shape determines call volume because Etherscan exposes balances, transaction families and event logs through separate API actions.

The single-address native balance action handles one address. Its multiple-address counterpart accepts up to 20 addresses per call, which cuts 20 separate balance reads to 1 when every address shares a chain. A latest-balance request also accepts a specific block within the last 128 blocks; older state belongs on the 2-call historical endpoint.

Transfer Families

Address Histories

Normal transactions and internal transactions use different actions. ERC-20, ERC-721 and ERC-1155 transfers each use another action because their records follow different token standards. A complete account activity view therefore fans out before pagination starts, and every chosen chain repeats that endpoint set.

Event Logs

Event-log queries filter by address, block range and topics, with up to 1,000 records in the documented address-and-topics query. A focused topic0 and contract address reduce both response size and page count. Logs expose protocol events directly, while address-history endpoints provide normalized transfer records.

Choose the narrowest endpoint that already matches the output rather than rebuilding every answer from a broad log scan.

Usage Monitoring Turns Caps Into Capacity Decisions

Capacity monitoring turns Etherscan limits into operating signals before queue delay reaches users or daily credits run out.

The API usage action reports credits used, credits available, the credit limit, the daily interval and the remaining interval timespan. Record those fields beside request rate, endpoint class, cache hits, retries and queue wait. Averages alone hide bursts, so inspect peak release rate and the strict 2-call bucket separately. Dashboard refreshes and scheduled backfills also need distinct labels because one serves live demand while the other can pause.

If the general bucket stays idle while historical work queues, a higher general rate won’t clear that endpoint ceiling. Improve batching or spread the backfill. If daily credits fall despite caching and narrow queries, the real decision is a larger allowance or a different data architecture.