Etherscan API: Intelligence Source Guide

Etherscan is the de facto public record of Ethereum, and its API turns that record into JSON: transactions, token transfers, internal calls, verified contract source and ABIs, behind a free key. The address labels everyone relies on are a website feature, not an API one.

At a glance

Source	Etherscan API
Category	Cryptocurrency & Blockchain › Blockchain Explorers
Homepage	https://etherscan.io/
Machine interface	https://api.etherscan.io/api
Format	JSON
Access	Free registration — API key at no cost
Disciplines	Cryptocurrency Intelligence
Mission domains	Financial Crime

Ethereum explorer + address labels. — as catalogued in the platform’s own source registry.

Etherscan is a block explorer for Ethereum that has become the ecosystem's default reference point – for developers reading contracts, for users checking transactions, and for investigators reconstructing what happened. Its API exposes the indexed chain over HTTP with a key, organised into modules rather than REST resources: an account module returning normal transactions, internal calls, token transfers and balances for an address; a contract module returning verified source code, ABIs and compiler metadata; a logs module for filtered event queries; a proxy module passing standard node calls through; and modules for statistics, gas and tokens. Responses come back in a consistent envelope carrying a status, a message and a result. Two structural facts govern everything you do with it. Every numeric value is returned as a string, including block numbers and wei amounts, so type handling is your problem from the first line of code. And result sets are capped, which means any address busy enough to matter must be collected in block ranges rather than in one call. Etherscan also builds and operates explorers for many other EVM networks under the same design, and has moved toward a versioned multichain interface addressed by chain identifier – confirm which version and base URL your key corresponds to rather than copying an example.

The analytical job Etherscan does that no generic index does is expose the contract layer. On Ethereum most activity of interest is not a simple transfer between two addresses; it is a call into a contract that emits events, moves tokens on behalf of others, and triggers further internal calls, and none of that is visible if you only read the transaction's from and to fields. The API surfaces three things that make this layer legible: verified source code and ABIs, so you can read what a contract actually does rather than guess from its bytecode; internal calls derived from execution traces, so value movement inside a transaction is visible; and token transfer lists derived from event logs, so you can follow assets that never appear as native value at all. For investigation this is decisive. An approval-drainer phishing operation, a rug pull, a bridge exploit and a straightforward theft all look different at the contract layer and nearly identical at the transfer layer. The second contribution is the labelling ecosystem on the website, which names exchanges, protocols, known incident addresses and reported phishing infrastructure – genuinely useful, widely relied upon, and specifically not part of what the API returns.

Who publishes it, and why that matters

Etherscan is a private company that has operated the explorer since Ethereum's early years and has become infrastructure the ecosystem depends on without ever having been designed as such. Revenue comes from paid API tiers, advertising on the site and enterprise services; the free tier exists and is genuinely usable, which is why nearly every wallet, dashboard and analytics product has at some point been built on it. Three consequences deserve thought. First, this is a single private point of dependency for an enormous share of Ethereum tooling, and its outages are ecosystem events – which is an argument for having a node-based fallback rather than for avoiding it. Second, its labels are a proprietary editorial product built from submissions, partnerships and its own research, with no published methodology and no appeal process visible to outsiders, so a label is an assertion by a company rather than a verified fact. Third, contract verification is voluntary and free, which is why so much of it exists and why its absence on a contract tells you something in itself. The service has been stable for a long time; plan for the version and endpoint changes that come with a maturing commercial product rather than for disappearance.

Provenance is the first question to ask of any dataset and the one most often skipped. Who collects it, what their incentive is, whether they publish a methodology, and whether they correct the record when they get something wrong all bear directly on how much weight a finding drawn from it can carry.

What a record actually contains

The fields you will be working with, what each one means, and whether it is something you can pivot on. Read the meanings carefully — more analysis is wrecked by misreading a field than by failing to find one, and a field that looks like an observation is often an inference.

Field	Type	What it means	Pivot value
hash	string	The transaction identifier. On an account-model chain this genuinely does identify one operation initiated by one sender, unlike the UTXO case, but the operation may internally involve dozens of parties through contract calls that the top-level fields do not show.	The internal call list for the same hash, the event logs it emitted, and any independent explorer for verification.
from	string	The initiating address. It is the account that signed and paid for the transaction, which is not necessarily the beneficial owner of the value moved – relayers, contract wallets and account abstraction all separate the payer from the party in interest.	The address's full history, its funding source, and the same string on other EVM chains where it is often the same controller.
to	string	The direct recipient, which on the majority of interesting transactions is a contract rather than a person. Reading a contract address as a counterparty is the single most common misinterpretation of Ethereum data by analysts trained on simple transfers.	The verified contract source and ABI, the internal calls the transaction produced, and the token transfer events it emitted.
value	string	Native currency moved by the top-level transaction, denominated in wei and returned as a string. A great many significant transactions have a value of zero because the assets that moved were tokens, and an analysis that filters on non-zero value will miss most of what matters.	The token transfer list for the same hash, which is where the actual asset movement usually is.
timeStamp	timestamp	Block time as a Unix seconds value in a string. Adequate for sequencing at second-to-block resolution within a chain, and not a basis for fine-grained claims about ordering across chains where clocks and block intervals differ.	Block number for exact ordering, and off-chain event timelines for correlation.
blockNumber	string	The containing block height, returned as a string like everything else. This is the correct ordering key and the correct anchor for any historical state claim, and it is what you should slice collection by when an address exceeds the result cap.	The block's other transactions, and the chain state at that height for balance reconstruction.
isError	enum	Whether the transaction reverted. Failed transactions are recorded on-chain, cost gas and appear in the list, and they are analytically valuable – a sequence of failures often shows an attacker calibrating an exploit before it worked.	The transaction trace, the contract source to see which condition failed, and the successful attempt that followed.
input	string	The calldata sent with the transaction, whose first four bytes identify the function invoked and whose remainder encodes the arguments. With the ABI from the contract module this decodes into a readable call, which is where the actual intent of a transaction lives.	The verified ABI for decoding, and other transactions calling the same function selector across the chain.
contractAddress	string	Populated when a transaction deploys a contract. Deployment transactions are high-value analytical objects: the deployer is a strong attribution lead, and the deployment time bounds when an operation was prepared.	The deployer's address and its funding history, and other contracts deployed by the same account.
tokenSymbol	string	The symbol reported by a token contract in a transfer record. Symbols are self-declared, non-unique and trivially spoofed – impersonating a major stablecoin costs nothing – so the contract address is the identity and the symbol is decoration.	The token contract address, its source code, its holder distribution and whether it trades anywhere real.
tokenDecimal	string	The decimal precision declared by the token contract, needed to convert a raw transfer amount into a human figure. Non-standard values exist and malicious tokens declare misleading ones, so a converted amount is only as trustworthy as this field.	The contract source, which is where the declared decimals can be confirmed rather than assumed.
traceId	string	The position of an internal call within a transaction's execution trace. Internal calls have no transaction hash of their own – they share the parent's – and treating them as separate transactions produces double counting that is very hard to detect downstream.	The parent transaction and its full trace, which shows the sequence of calls that produced the movement.
SourceCode	string	Verified source for a contract, returned with compiler version, optimisation settings and, for proxy patterns, implementation details. Verification is voluntary, so its absence is itself a signal – unverified contracts handling significant value are worth attention.	The ABI for decoding calls, similar verified contracts sharing code, and the deployer's other deployments.
status	enum	The envelope-level result indicator, distinct from the transport status. A rate-limit rejection, an empty result and a malformed request all return a successful transport response with an unsuccessful envelope, and a client that only checks the transport layer will record failures as empty findings.	The accompanying message field, which distinguishes no results found from an error condition and should drive different handling.

Coverage — and what is not in it

Ethereum mainnet from genesis, complete, including transactions, internal calls derived from traces, token transfers derived from event logs, contract deployments and verified source where developers have submitted it. Test networks are covered under separate endpoints. Etherscan's design has been replicated across a large set of other EVM networks by the same operator, and the move toward a unified multichain interface keyed by chain identifier means one key can increasingly serve many chains through one base URL – verify the current arrangement for your key rather than assuming, since this area has changed. Verified contract coverage is broad for anything with users, because verification is free and reputationally expected, and thin for infrastructure built to avoid scrutiny, which makes the gap informative. Label coverage on the website is dense on exchanges, major protocols, bridges and publicly reported incident and phishing addresses, and absent for the long tail – and it is a website feature that the standard API does not return, which is the most consequential coverage fact in this entry. Update cadence follows the chain with a short indexing delay, and internal calls and token transfers can appear marginally behind the transactions that produced them.

Known blind spots

Absence of evidence here is not evidence of absence. These are the conditions under which Etherscan API will not show you something that is nevertheless real:

• The API does not return the address labels the website displays. This is the single most misunderstood thing about the source: an integration built expecting labelled output will get bare addresses, and analysts who saw a name on the site will assume the pipeline has it too.
• Result sets are capped per query, so any address with substantial history returns a truncated list. Without block-range slicing your collection is incomplete in a way that produces no error and no warning.
• Internal calls are reconstructed from execution traces and are not transactions. They share the parent hash, they are not independently verifiable in the same way, and counting them alongside transactions double counts value.
• Token transfers are derived from event logs, which a contract can emit dishonestly. A transfer event is a claim by a contract that a transfer occurred, and malicious tokens emit events that do not correspond to any real balance change.
• Value in the top-level transaction fields is native currency only, so an analysis keyed on it misses the majority of economically significant activity, which moves as tokens.
• Off-chain and layer-two activity is invisible unless it settles on the network you are querying. Rollup-internal transactions, exchange-internal transfers and bridged value all leave gaps that look like the trail ending.
• Contract verification is voluntary and unverified bytecode is opaque to this API, so the contracts most likely to be hostile are the ones you can read least.
• The service is a single private dependency for a large part of the ecosystem, and an outage or an unannounced endpoint change breaks pipelines that had no fallback because nothing had ever broken before.
• Sibling explorers on other chains look identical and are not guaranteed to be identical in endpoints, field availability or limits, so code that works against one may fail subtly rather than loudly against another.

Write the blind spot into the product. A statement that something “was not observed in Etherscan API” is defensible; a statement that it “did not happen” is not, and the difference is what survives cross-examination.

Access, licensing and what you may do with it

Access model: Free registration — an account or API key, at no cost

A free API key is available on registration and is enough for real investigative work: single-address collection, contract source retrieval, spot verification. The free tier carries a low per-second rate limit – five calls per second is the long-standing figure – together with a daily allowance, and paid tiers raise both and unlock additional endpoints. Confirm the current limits and the endpoint version associated with your key on the documentation rather than relying on any example, because the API has been through a versioning transition toward the multichain interface and older per-explorer endpoints have been on a deprecation path. The practical architecture question is what you do when the API is not the right tool: for large historical extractions, for anything requiring guaranteed availability and for confidentiality-sensitive queries, the answer is your own node with a tracing and indexing layer, which is a significantly heavier engineering commitment on Ethereum than the equivalent on Bitcoin but removes the dependency entirely.

Licence

Proprietary service with terms of service governing use, and the terms are the operator's to change. The underlying chain data is public and unowned, so nothing restricts your use of transactions, balances or contract bytecode you could derive from a node yourself. The service, the index, the labels and the verified source presentation are the operator's product. Standard restrictions apply: use within your allowance, no reselling of the API as a service, no scraping the website to obtain what the API does not provide – and that last point matters specifically because the labels are website-only and scraping them is the obvious temptation and the clearest violation. Verified contract source is published by developers and its licensing is whatever those developers chose, which is often an open licence declared in the file header and sometimes nothing at all; do not assume you may redistribute source merely because it is publicly readable. Confirm current terms before commercial reliance.

Rate limits and fair use

Two limits govern free use: a strict per-second cap and a daily allowance. The per-second cap is the one that breaks naive integrations, because a straightforward loop over an address list will exceed it immediately and the rejections come back as successful transport responses with an error in the envelope – so a client that does not inspect the envelope will silently record empty results as findings. Build for this from the start: a token bucket at the client, exponential backoff on envelope errors, and permanent caching of anything historical, since confirmed transactions never change. Prefer one call that returns everything you need over several narrower ones, and slice large address histories by block range with a stored cursor so an interrupted collection resumes rather than restarts. Put a hard daily ceiling in your own collector. Every team that has run out of quota overnight did so because a retry loop had no upper bound.

Licensing changes, and it changes without warning. A dataset that was free for research this year may not be free for commercial or evidential use next year. Confirm the current terms before you build a dependency on it, and record the terms you relied on alongside the data — the licence in force at the time of collection is part of the provenance.

Collecting it

How Etherscan API is actually pulled, in the order you would set it up. Prefer the bulk or export interface over per-item lookups wherever one exists: it is kinder to the publisher, faster for you, and gives a reproducible snapshot rather than a series of point-in-time answers you cannot reconstruct later.

Method	Format	Cadence	Notes
Address transaction history by block range	JSON	Per case, then incrementally	The core operation. Slice by block range to stay under the result cap, store the highest block collected, and resume from it. Collecting an active address in one call is the most common way to end up with a partial history you believe is complete.
Token transfer collection	JSON	Alongside every transaction pull	Separate endpoints return token movements derived from event logs. Most economically significant activity is here rather than in native value, so an address collection that omits token transfers has missed the substance.
Internal call retrieval	JSON	Per transaction of interest	Value movement inside contract execution. Essential for understanding exploits and routed transfers, and dangerous if merged with transactions in the same table, because they share the parent hash and will double count.
Contract source and ABI retrieval	JSON	Once per contract, cached permanently	Verified source, compiler metadata and ABI. Cache indefinitely: a verified contract's source at a given address does not change, and the ABI is what makes every subsequent calldata decode possible.
Event log queries	JSON	Per analytical question	Filtered log retrieval by address and topic, which is how you find every occurrence of a specific event such as an approval or a transfer of a particular token. The nearest thing this API offers to a population query.
Node passthrough for state queries	JSON	As needed	The proxy module forwards standard node calls, which is how you obtain historical state at a specific block. Convenient for occasional use and not a substitute for your own node at volume.

Ingesting it into the platform

Every step below is idempotent and cursor-based: interrupt one and it resumes from where it stopped rather than duplicating rows or losing progress. Collection is recorded per source, so a feed that quietly stops publishing shows up as a stale timestamp instead of silently thinning your coverage.

1. Register per chain with its own key state — sources.php holds a separate registration for each EVM network collected, because limits, endpoint versions and field availability differ even where the interface looks identical. One aggregate registration hides which chain is failing.
2. Store the envelope, not just the result — ingest.php records the status and message alongside the payload so a rate-limit rejection is distinguishable from a genuinely empty history. Without this, throttling is indistinguishable from an address having no transactions, and the pipeline reports a clean result.
3. Slice by block range and persist the cursor — collect.php walks address histories in block ranges, storing the highest block collected per address. This is what makes collection complete, resumable and incremental rather than a full re-fetch that will hit the cap again.
4. Keep transactions, internal calls and token transfers in separate tables — Each has different semantics and different verifiability. Internal calls share the parent hash and token transfers are contract assertions, so merging them into one transfer table produces double counting and unearned confidence in equal measure.
5. Normalise wei and token units at ingest — All numerics arrive as strings in base units. Conversion happens once at the boundary using the token's declared decimals, with the raw value retained, because a malicious or non-standard decimals value should be visible rather than baked into a number nobody can check.
6. Cache verified source and ABIs permanently — enrich.php stores contract source, compiler metadata and ABI keyed by chain and address. This is immutable data, it is expensive to re-fetch, and having the ABI locally is what lets calldata be decoded during analysis rather than during collection.
7. Screen addresses against designation lists — sanctions.php checks collected addresses against authoritative sources directly. The API returns no labels and no risk information at all, so screening is an explicit step that must be added rather than something inherited from the source.
8. Correlate, case and export — correlate.php links addresses recurring across investigations, link-analysis.php renders the contract-layer relationships, and export.php emits CSV, JSON or MISP. Summarise (Copilot) writes narrative over collected records; no indicator or attribution in the platform originates from a model.

Registered sources and their last-collected state are listed in sources.php, and the scheduled chain that keeps them current is in automation.php.

How it is wrong, and how to tell

Every dataset is wrong in characteristic ways. Knowing which ways is the difference between using a source and being used by one, and it is the part of source evaluation most often skipped because it is the part that takes work.

The chain data is accurate and independently checkable against any node, which puts the factual layer in the same high-integrity category as any good index. Internal calls and token transfers sit one step further away from consensus: internal calls are reconstructed from execution traces, which is a well-defined derivation but a derivation nonetheless, and token transfers are read from events that a contract chose to emit and can therefore lie about. Neither is a defect, but both are reasons to say derived from rather than recorded on when it matters. Verified contract source is high quality where present because the verification process compiles the submitted source and matches the resulting bytecode, which is a real check rather than an assertion. The labels on the website are the weakest element – editorially curated, methodologically undocumented, without appeal, and outside the API entirely – and they should be treated as leads regardless of how authoritative they look. The service's operational reliability has been strong for years, which has induced a level of ecosystem dependence that is itself the main risk, since almost nothing built on it has a tested fallback.

Characteristic false positives

• Truncated address histories accepted as complete. The result cap returns a valid response containing part of the story, and every subsequent conclusion inherits an omission the analyst never saw.
• Contract addresses read as counterparties. Routers, aggregators, proxies and multicall contracts appear in the to field constantly, and treating them as parties turns a two-party interaction into a fictitious multi-hop network.
• Fake token transfers taken at face value. Contracts can emit transfer events that correspond to nothing, and address-poisoning operations deliberately generate transfers from lookalike addresses to contaminate transaction histories and induce mistaken payments.
• Internal calls double counted against transactions. They share the parent hash, so a naive merge inflates both transfer counts and total value moved, sometimes by a large factor and always invisibly.
• Symbol and decimals trusted over contract identity. A token declaring a major stablecoin's symbol and eighteen decimals is trivial to deploy, and a value computed from those declarations can be wrong by any factor its author chose.
• Zero-value transactions filtered out as noise. Approvals, contract calls and administrative operations often carry no native value while being the most important events in an incident, and value-based filtering removes exactly the evidence you need.
• Rate-limit rejections recorded as empty results. The envelope reports the error while the transport reports success, so an unexamined client stores absence of data as a finding of no activity.
• Cross-chain address identity assumed. The same string exists on every EVM chain and often has an unrelated history on each, so a record without a chain identifier merges distinct entities into one.

None of these make the source unusable. They make it a source that requires corroboration before an assertion built on it goes into a product, which is true of every source and admitted by few.

Ageing

Confirmed transactions, internal calls, token transfers and verified source are permanent and should be cached indefinitely; re-fetching them is the largest avoidable waste in most integrations. Balances and token holdings age on the block interval, which on Ethereum is seconds, so any balance in a report needs a block number attached or it is a statement about nothing in particular. Contract behaviour ages in a way peculiar to this chain: an address holding a proxy can have its implementation replaced, so the code that governs an address today may not be the code that governed it when the transactions you are analysing occurred, and analysing current source against historical transactions is a real and frequently made error. Website labels age on the operator's editorial cadence with no version history, so a label observed today may differ from one observed last year with no way to reconstruct which you relied on. The characteristic stale artefact is an analysis of a proxy contract using its current implementation, describing behaviour that was not in effect at the time of the events under examination and doing so with complete confidence.

What this source feeds

A source is only worth what it lets you conclude. These are the disciplines that collect through it, the mission domains it serves and the data points it yields — every one is a tag, so you can follow any thread from here into the rest of the library.

Collected by these intelligence disciplines

• Cryptocurrency Intelligence

Serves these mission domains

• Financial Crime

Yields these data points

• Cryptocurrency Address
• Transaction Hash

How each sector uses Etherscan API

The same dataset is worked very differently depending on who you are, what authority you hold, and what you are ultimately producing. A military analyst is supporting a commander’s decision; a journalist is meeting a publication standard; an NGO caseworker is protecting a person. The records are shared — the constraints, thresholds and outputs are not.

🎖 Military and defence

The relevant use is characterising the contract-layer infrastructure of financially motivated actors and, in threat finance work, verifying indicators independently of the tracing vendors. The API supports the specific questions that matter for infrastructure assessment: who deployed a contract, when, from what funding source, and what other contracts that account has deployed – which is often a stronger attribution lead than any flow analysis, because deployment requires an account with history. Two constraints for staff use. There is no attribution here and no labelling in the API, so this answers what and when and never who without a separate source. And queries disclose interest to a commercial operator, so anything sensitive should run against infrastructure you control, which on Ethereum means a node with tracing enabled and is a heavier commitment than the Bitcoin equivalent. Verified contract source is unclassified, citable and shareable with partners, which makes it good material for coalition assessments.

🕵 National intelligence

In the CRYPTINT lane the contract layer is where actor tradecraft is visible in a way that flow analysis cannot show. Deployment patterns, code reuse across contracts, distinctive function selectors, gas parameter habits and failed-attempt sequences before a successful exploit are all behavioural signatures with real persistence, and they support association between operations where the money trail has been laundered into silence. Verified source is a particularly rich selector: reused code with the same idiosyncratic comments or structure links deployments that share no addresses. Collection discipline is unchanged – cache permanently, slice by block range, keep the envelope, and record the chain with every address – and the exposure question is the usual one: every query tells a private company which address you are examining, which is acceptable for open indicators and not for sensitive ones.

👮 Law enforcement

For investigators the decisive contributions are the contract layer and the token layer, because in most Ethereum fraud and theft cases the assets that moved were tokens and the mechanism was a contract call. Being able to show that a victim signed an approval, that a drainer contract subsequently transferred their holdings, and that those holdings moved through a named service is a complete narrative built from primary data. Practical discipline: collect the full history by block range rather than accepting a truncated list, keep internal calls separate from transactions so your value figures are not double counted, and verify the token contract rather than trusting the symbol. Website labels are hearsay and should not appear in an affidavit; state the underlying transactions instead. And be alert to address poisoning in a victim's history, which plants lookalike addresses specifically to create false leads and mistaken payments.

🔍 Private investigation and corporate security

For asset tracing on Ethereum this is the primary technical source and it is free at the tier most work requires. It answers the client's core questions – what moved, when, to what, and is any of it still there – with data that can be independently verified by the other side, which is exactly what you want in a report that may end up in front of a court. The contract layer is where the value is: identifying that a loss occurred through a signed approval rather than a compromised key changes both the recovery strategy and the client's insurance position. Cautions: do not quote a website label to a client as identification of a person; do not present a token amount without confirming the contract and its declared decimals; and attach block numbers to every balance you state, because in a fast-moving matter a figure without a height will be wrong by the time the report is read.

📰 Journalism and OSINT media

The best free source for verifying claims about Ethereum activity, and the right one to cite because readers can check it themselves. It is particularly strong for stories about contracts: whether a project's code was verified, who deployed it, whether an administrative function allows the team to do what they said they could not, and what actually happened during an incident. Publish transaction hashes and contract addresses. Distinguish clearly between what the chain records and what a label asserts, since Etherscan's labels are an editorial product of a private company and readers will otherwise take them as authoritative. Be careful with token amounts and symbols, which are self-declared and are routinely spoofed to inflate apparent value – verifying the contract address takes a minute and prevents a correction.

🌍 NGO, humanitarian and human rights

Relevant to fraud and exploitation casework where a victim's losses ran through Ethereum, and to research documenting how such operations are structured. The contract layer often explains the mechanism in a way that helps a victim understand what happened – that they authorised a spending permission rather than had a password stolen – which matters for their own account of events and for any claim they make. Beyond that, the practical priorities are referral to the appropriate national reporting channel and protection from recovery-fraud operators who target victims a second time and are very active in this space. Handle addresses linked to identified people as sensitive personal data, and note that a victim's address in a public report is permanently linkable to their transaction history by anyone who reads it.

🎓 University and research

Widely used in research and worth using carefully. The API is a convenient route to Ethereum data at moderate scale, and verified contract source is a substantial corpus supporting work on code reuse, vulnerability prevalence and deployment practice that is difficult to assemble any other way. Three methodological cautions. Result caps mean a naive collection is a biased sample toward low-activity addresses, and that bias is systematic rather than random. Token transfer data is derived from contract-emitted events and is not ground truth about balances. And website labels are a proprietary editorial classification, unversioned and unreproducible, so they should not be used as ground truth in supervised work. For anything requiring completeness or reproducibility, archive node data with tracing is the defensible source and this is the convenience layer.

Playbook: working Etherscan API end to end

A repeatable sequence from first pull to finished product. Each phase states what you are trying to establish, not merely what to click — the objective is a defensible chain of reasoning, not a completed checklist.

Phase 1 — Fix the chain and the version before writing any code

Confirm which chain identifier and which API version your key addresses, because the interface has been consolidating toward a multichain form and older per-explorer endpoints have been on a deprecation path. An integration built against a stale example will work until it does not, and the failure will arrive at an unhelpful moment.

Phase 2 — Collect the full history by block range

Slice the address history into block windows sized to stay under the result cap, and persist the highest block collected. Verify completeness by checking that consecutive windows meet without gaps. An address history collected in one call is a partial history whenever the address is interesting enough to be worth collecting.

Phase 3 — Pull transactions, internal calls and token transfers as three separate collections

They come from different endpoints and mean different things: transactions are consensus records, internal calls are trace derivations sharing the parent hash, token transfers are contract-emitted claims. Keeping them separate throughout is what prevents double counting and unearned confidence in the totals.

Phase 4 — Resolve every contract you touch

For each contract address in the picture, fetch the verified source and ABI and cache them. Read enough of the source to know what the contract does, particularly its administrative functions and whether it is a proxy. Analysing transactions against a contract you have not read is guessing with extra steps.

Phase 5 — Check whether a contract is a proxy and which implementation was live

Proxy patterns separate the address from the code, and the implementation can be replaced. For any historical analysis, establish which implementation was in effect at the relevant blocks rather than reading today's source. This is a routine error and it produces confident descriptions of behaviour that was never in effect.

Phase 6 — Decode calldata rather than reading the value field

Use the ABI to decode the input data and establish what function was called with what arguments. Zero-value transactions are frequently the important ones – approvals, administrative changes, exploit calls – and an analysis keyed on native value will pass straight over them.

Phase 7 — Verify token identity by contract address

For every token in the analysis, confirm the contract address, read its source, and check its declared decimals and its market reality. Symbol spoofing is trivial and common, and a report quoting a large stablecoin figure that turns out to be a worthless impersonation is a specific and recurring embarrassment.

Phase 8 — Screen the history for address poisoning

Look for transfers of zero or negligible value from addresses that closely resemble legitimate counterparties. These are planted to corrupt transaction histories and induce mistaken payments, and in a victim's history they generate false leads that consume analyst time and can misdirect an entire investigation.

Phase 9 — Reconstruct the incident as a sequence of calls

For an exploit or theft, order the relevant transactions by block and index and describe what each call did using the decoded input and the internal calls. Include the failed attempts – a sequence of reverts before a success shows preparation and calibration, and is often the most probative material available about intent.

Phase 10 — Sweep the same address string across sibling chains

EVM addresses exist on every EVM network and are frequently controlled by the same key everywhere. Checking the other chains is cheap and regularly finds funding, staging or cash-out activity absent from the chain you were given. Record each result against its own chain identifier.

Phase 11 — Screen against designation lists explicitly

The API returns no labels and no risk information, so sanctions screening is a step you add. Check against authoritative sources directly, record the date, and be precise about which address was listed – designation attaches to specific addresses and extending it by inference is a legal argument rather than a finding.

Phase 12 — Record provenance and cache everything immutable

Store the chain, the endpoint version, the collection time and the block range for every collection, and cache confirmed transactions and verified source permanently. This makes the analysis reproducible, keeps you inside the rate limits, and means a later reviewer can see exactly what you had rather than what the API returns today.

The platform ships this as a step-checked workflow in playbooks.php, so progress is recorded against a case rather than held in someone’s head.

What to pair it with

No single source carries a finding. These are the datasets that corroborate, extend or contradict this one — and a source that contradicts is worth more than one that agrees, because it is the only thing that will tell you when you are wrong.

Source	Relationship	What it adds
Blockchair	corroborates	Independent multi-chain index with a query API and bulk dumps, useful as a second opinion on Ethereum facts and for population-level questions this module-based API cannot express.
Blockstream Esplora	extends	The Bitcoin-side equivalent, self-hostable and open source, for cases that cross between account-model and UTXO chains and for the sensitive lookups that should not touch a commercial service.
MetaSleuth	extends	Adds cross-chain path tracing and entity labelling on top of the raw contract-layer data, covering the two things this API deliberately or incidentally omits.
MistTrack	extends	Risk categorisation and regional labelling, complementing an API that returns no attribution at all despite the website appearing to have plenty.
Ethereum Improvement Proposals	prerequisite	The specifications for address checksums, token standards and account abstraction that determine how the fields in this API should be interpreted and normalised.
Ethereum developer documentation	prerequisite	The reference for the account model, transaction lifecycle, event logs and proxy patterns – the grounding without which contract-layer analysis is pattern matching.
OFAC Sanctions List Search	prerequisite	Authoritative designations including listed digital currency addresses, which must be screened against separately because nothing in this API does it for you.
Chainabuse	corroborates	Community abuse reports keyed to addresses, providing the victim-side narrative that explains what a contract interaction meant to the person who signed it.

Legal, ethical and operational constraints

Reading public chain data is lawful everywhere that matters and requires no authority. The constraints are contractual, protective and evidential. The terms of service govern quota use and prohibit reselling and scraping – and the scraping prohibition is pointed here, because the labels most analysts want are on the website and not in the API, making unauthorised extraction the obvious shortcut and the clearest violation. Verified contract source is published by its developers under whatever licence they chose, so republishing it is a copyright question rather than a terms question. Addresses linked to identified people are personal data in most modern regimes, with the usual obligations attaching to your case files. For evidential use, prefer statements grounded in transactions that anyone can verify against a node over statements grounded in website labels, which are an unexplained editorial product of a private company and will not withstand a competent challenge. Sanctions obligations generally attach on knowledge, and since this source performs no screening, the duty to check sits entirely with you.

Operational security

Every query discloses to a commercial operator which address, contract or transaction you are examining, together with your API key, which ties the entire query stream to an identified account and, through registration, to your organisation. That is a far stronger identifier than an IP address and it persists across networks, so key hygiene is the main control: separate keys for separate programmes, never a shared organisational key across sensitive and open work, and rotation when personnel change. The query pattern itself is expressive – resolving a contract, then its deployer, then the deployer's funding source is a legible investigative narrative to anyone reading the logs. For sensitive work the alternative is an archive node with tracing, which is a substantial engineering and hardware commitment on Ethereum but is the only configuration that discloses nothing. Note also that the website and the API are operationally distinct, and browsing an address page while logged in is its own disclosure, made by a person rather than by a pipeline.

Two rules that hold regardless of jurisdiction. Collection that is lawful is not automatically proportionate, and a dataset assembled for one purpose does not carry consent for another. Where the records concern identifiable people, the question is not only whether you may hold the data but whether holding it serves the purpose you are accountable for.

Is it earning its place?

Sources accumulate. Feeds get added during an incident and are never reviewed again, and a decade later the pipeline is carrying dead weight that nobody dares remove. These are the measures that show whether Etherscan API is contributing anything, and they are worth baselining now so the answer is available later.

• Proportion of address collections verified complete by block-range reconciliation rather than assumed complete, which is the direct measure of whether the result cap is being handled.
• Rate of envelope-level errors treated as empty results in the pipeline, which should be zero and is rarely measured until it has already corrupted an analysis.
• Cache hit rate on confirmed transactions and verified source, since anything below very high means quota is being spent re-fetching immutable data.
• Number of contracts in case files with source and ABI resolved and cached, as a share of contracts encountered – the practical measure of whether analysis is happening at the contract layer or the transfer layer.
• Frequency of token-identity verification by contract address before an amount is quoted, which is the specific control against symbol spoofing.
• Cross-chain sweeps performed per new EVM address, and the hit rate of those sweeps, which tells you whether the practice is earning its cost on your case mix.
• Instances where analysis was performed against a proxy's current implementation rather than the historically live one, found by review, which should trend to zero as the check becomes routine.

Beware of volume. Indicator counts rise easily and say almost nothing. Unique contribution — findings this source produced that no other source in your stack would have — is the measure that matters, and it is usually far lower than anyone expects.

Tradecraft notes

The distinctions that separate a competent analyst from a fast one:

• The labels are on the website, not in the API. Design your integration around that fact rather than discovering it after building an enrichment step that returns nothing.
• Slice by block range or your history is a fragment. The cap fails silently, and no part of the response will suggest that anything is missing.
• Most of what matters carries zero native value. Approvals, contract calls and administrative changes move nothing and decide everything, and value-based filtering deletes them.
• Read the contract. An analysis of transactions against code you have not looked at is a description of activity whose meaning you have guessed.
• Check for a proxy before you cite behaviour. Implementation code can be replaced, and today's source may not be what governed the transactions you are examining.
• Internal calls are trace derivations, not transactions. Keep them in their own table, state them as derived, and never add them to transaction counts.
• A token is its contract address. Symbol and decimals are self-declared, spoofable, and specifically chosen by hostile deployers to mislead an analyst reading quickly.
• Address poisoning is designed for you as much as for the victim. Lookalike addresses in a history are planted to create false leads and to induce a mistaken payment.
• Cache everything confirmed, forever. Immutable data re-fetched is quota spent on nothing, and quota is the constraint that decides how much real work you can do.

Questions analysts actually ask

Why does the API not return the labels I see on the website?

Because the labels are a website feature and a proprietary editorial product, not part of the standard API output. Building an integration that expects them will produce bare addresses. Scraping the site to obtain them violates the terms; the correct answer is a separate attribution source, or a commercial arrangement if you need labelling at scale.

Why is my address history incomplete?

Result sets are capped per query, so a busy address returns a truncated list with no error. Collect in block ranges with a stored cursor and confirm that consecutive windows meet without gaps. This is the most consequential integration detail in the whole API and it fails silently every time.

Are internal transactions real transactions?

No. They are value movements reconstructed from execution traces during contract calls, and they share the parent transaction's hash rather than having their own. They are analytically essential and they must be kept separate from transactions, because merging them double counts both events and value.

Can I trust the token transfer records?

They accurately reflect the events contracts emitted, which is not the same as accurately reflecting reality. A malicious contract can emit transfer events that correspond to no real balance change, and impersonation tokens are deployed precisely to produce misleading histories. Verify the token contract address before quoting any amount.

What does it mean when a contract is not verified?

That the developer never submitted source matching the deployed bytecode. Verification is free and reputationally expected, so its absence on a contract handling significant value is itself a signal worth noting. You can still analyse behaviour from transactions and events; you simply cannot read the intent.

Does one API key work across other EVM chains?

Increasingly yes, through the multichain interface addressed by chain identifier, but this has changed over time and the older per-explorer endpoints have been on a deprecation path. Check the current documentation for the version your key corresponds to rather than copying an example, and register each chain separately in your collection so failures are attributable.

How do I get a balance at a past date?

Reconstruct it from the transaction and token transfer history up to the relevant block, or use a node call for historical state at that block through the proxy module. Either way, state balances with a block number attached. A bare balance on a chain with second-level block times is a claim about a moment nobody can identify.

Should I run my own node instead?

For sensitive queries, for guaranteed availability and for large historical extractions, yes – an archive node with tracing removes the dependency and the disclosure. It is a substantially heavier commitment than the Bitcoin equivalent in both storage and operational effort. Most teams use the API for the bulk of work and a node for the queries that must not leave their control.

Is a website label good enough for a report?

As a lead, yes. As a stated fact about a person, no. The labels are curated by a private company with no published methodology and no visible appeal process, and they name services rather than people. State the underlying transactions, which any reader can verify, and treat the label as the reason you looked rather than as the finding.

Standards, formats and interoperability

What this source speaks natively, and what it has to be translated into before a partner can consume it. Work that arrives in a recognised format is easier to defend, easier to hand over and easier to automate against:

• The Ethereum account model and transaction lifecycle, including gas accounting and the distinction between a transaction and the internal calls it produces.
• ERC-20, ERC-721 and ERC-1155 token standards, which define the transfer events that token movement records are derived from and the decimals convention that governs amounts.
• EIP-55 mixed-case checksum encoding, the reason address case is meaningful and the check that catches transcription errors before they enter a case file.
• Contract verification through source-to-bytecode matching, which is what makes published source trustworthy rather than merely available.
• Proxy patterns and upgradeable contract conventions, which separate an address from the code that governs it and are essential to historical analysis being correct.
• Chain-agnostic account identifiers for expressing chain plus address as one portable identity across the EVM ecosystem.
• MISP cryptocurrency attribute types for sharing address indicators with partners, since STIX 2.1 has no native cryptocurrency observable in its core specification.

References

Primary documentation and authoritative references for this source. Publishers revise and retire material, so treat the retrieval date as part of the citation and re-check before relying on any of it in a formal product.

1. Etherscan — Etherscan. The explorer itself, including the label and contract verification features that the API does not expose. The reference point for what is actually available before you design an integration.
2. Etherscan API documentation — Etherscan. The authoritative reference for modules, actions, parameters, rate limits and the current versioning arrangement. Read the limits and versioning sections properly; both have changed.
3. Ethereum developer documentation — Ethereum Foundation. Grounding in the account model, transactions, event logs and proxy patterns, without which the API's fields can be parsed but not interpreted.
4. Ethereum Improvement Proposals — Ethereum Foundation. The specifications for address checksums, token standards and account abstraction that determine correct normalisation and correct reading of transfer records.
5. Solidity documentation — Solidity. Necessary for reading verified contract source with understanding, particularly around access control, upgradeability and the patterns that show up repeatedly in incidents.
6. Blockchair — Blockchair. Independent index for cross-checking Ethereum facts and for the population-level queries a module-based API cannot express.
7. Blockstream Esplora — Blockstream. The Bitcoin-side counterpart, open source and self-hostable, for cases spanning both transaction models and for queries that must not touch a commercial service.
8. OFAC Sanctions List Search — US Department of the Treasury, Office of Foreign Assets Control. Authoritative digital currency address designations. Screening is entirely your responsibility here, because nothing in this API performs it.
9. Financial Action Task Force — FATF. The virtual asset standards that define which entities in a flow are regulated and what a disclosure request to them can realistically ask for.
10. Chainabuse — Chainabuse. Community abuse reports keyed to addresses, often the only source that explains what a contract interaction meant from the victim's side.
11. Internet Crime Complaint Center — US Federal Bureau of Investigation. Victim reporting channel and publisher of fraud typologies, including the approval-drainer and recovery-fraud patterns that dominate Ethereum victim casework.
12. MISP Project — MISP. The sharing platform whose native cryptocurrency attribute types are the practical route for exchanging on-chain indicators with partners.

Link integrity: every reference above was verified with a live request when this page was generated. Where a publisher had moved or withdrawn a document, the link was repointed at a preserved copy in the Internet Archive and marked as archived. Anything with no reachable copy anywhere had its link removed rather than left to rot — the source is still credited, it simply cannot be linked.

Put it into practice

The Quantus Intel threat intelligence platform operationalises this source: it collects address histories in block ranges with a persisted cursor so nothing is silently truncated, keeps transactions, internal calls and token transfers in separate tables with their differing provenance intact, caches verified source and ABIs so calldata can be decoded during analysis, and screens every collected address against sanctions.php because the API itself returns no attribution at all.. Browse the full source catalogue, or follow any tag above into the rest of the library.