Data sources and limits

Data sources and limits

Where the data comes from, balances, the backup server, rate limits, running your own server, Tor and outside look-ups.

• Balance of each address - the details of a wallet show its balance: what the server says it holds now (everything it ever received minus everything it spent, confirmed), its unconfirmed movement apart, what it received and sent in total on chain, and when and from which server that was read. Valued at today's price when a currency is chosen. Loading an address's history reads it; for a wallet whose balance is not known the details say so and Load balance asks the server for just that (one request, no history). Select several wallets and the details list every balance, largest first, with the total, and Load n balances reads the missing ones (one request each, at most 100 at a time, under the usual request limit). Balances are in the exports (balance_sat, balance_pending_sat, balance_as_of_utc; empty, not zero, where never read), the saved session and the report's wallets table. Received here and Sent from here are different: they count only the transactions loaded in this graph.

Data sources. mempool.space, mempool.space over Tor, Blockstream.info (the same Esplora API) or your own Esplora URL. Blockstream.info has no price API, so fiat prices still come from mempool.space (only the currency and the dates are sent there); with Tor selected prices are fetched over Tor as well. Other providers that are not Esplora-compatible (Blockchair, BlockCypher, and attribution services such as Arkham) would each need their own adapter and, for most, an API key. A key for your own server: for My own Esplora URL, Key or token (optional) is sent with every request to that server, in the header you name (Authorization by default; a value without a scheme is sent as a Bearer token). It goes only to that server (never to the backup, and never into an address, an export or a report), is forgotten when the page is closed unless you tick Remember on this computer (the wallet overview then uses it as well), and a server that refuses it (HTTP 401 or 403) is reported as that. The same place sets how many requests run at once and the pause between them: your own server starts at 8 at once and 20 ms apart, the public ones are paced at 4 and 150 ms.

External lookups (Arkham Intelligence). On request and for one wallet at a time (right-click it, or the button in its details; never for the whole graph), the workspace can ask Arkham Intelligence who a wallet belongs to. A web page cannot call Arkham's API: it sends no CORS headers (checked with a real browser), and an API key does not belong in a page anyway. So the call goes through tools/arkham_proxy.py, a small program you run on your own machine: it keeps the key in the ARKHAM_API_KEY environment variable, listens on 127.0.0.1 only, forwards nothing but GET /intelligence/address/<address>, requires a token that the page sends (so no other website can use your key), caches answers and limits its own request rate to protect your quota. Run it, then enter its URL and token under Controls > External sources. The first look-up asks for confirmation, because the address is sent to Arkham; look-ups are switched off while the data source is Tor, since they would leave Tor. The result is shown on the wallet with its raw reply and is never applied automatically: Use as label and Tag as … are buttons. Without a key or a proxy, right-click a wallet or a transaction (or use the details panel, or the top of the wallet overview) and choose Check in Arkham: it is a link to Arkham's own page for it, opened in a new tab with no referrer, so your own Arkham account is used if you are signed in there. Nothing is sent when the menu opens, only when you click, and Arkham is then told which wallet or transaction you are looking at. It is not offered while the data source is Tor. Not verified against a live key: Arkham's reference could not be read and no key was available, so the reply is parsed from the field names Arkham documents (arkhamEntity, arkhamLabel, populatedTags) tolerantly and the raw reply is always kept; if your account's reply looks different, the raw text is what you read. The proxy is covered by tests against a fake Arkham, including the key never being returned, logged or sent to the page.

Backup server. mempool.space is the default and Blockstream.info its backup (and the other way round if you choose Blockstream.info): both speak the same Esplora API. Under Data source, If it keeps failing, use … instead (on by default) lets the other one answer when the first throttles you (HTTP 429), returns a server error (5xx), does not answer in time or cannot be reached. A throttled request moves at once, the others after one retry, and the failing server is then left alone for about a minute before it gets the next request again. A "not found" is an answer and never moves a request. The page says when it switches (and when the first server answers again), the run summary says how many requests went to the backup, and each transaction records the server that actually sent it, which the report, CSV and GraphML show (a report can list both). Fiat prices are not affected: Blockstream has none, so they keep coming from mempool.space. The backup sees those look-ups as well, which is why the option can be switched off; it is never used with Tor (that would leave Tor) or your own server (a failing server of your own should be seen, not hidden).

Limits. mempool.space publishes no rate limit (a maintainer has said the limits are deliberately undisclosed) and sends no rate-limit headers; when it throttles it answers HTTP 429, and it may stop answering an IP that keeps asking. Blockstream.info publishes none either. Address history is paged 25 transactions at a time. The page therefore keeps its own limits (default: 4 requests in parallel with 150 ms spacing, 80 requests per action, 25 transactions per expand, 5-minute response cache; Auto-expand has its own limits, 40 transactions and 150 requests by default, and stops at whichever comes first), honours Retry-After, retries 429/5xx/timeouts with growing pauses, and shows the running request totals under Data source. For heavy use, run your own mempool/electrs instance and point My own Esplora URL at it.

Running your own Esplora server removes the public APIs' limits (mempool.space and Blockstream.info: the page paces itself and retries, but a long trace is slow and they may throttle you) and keeps every lookup on your own machine. Choose My own Esplora URL… under Data source (for example http://localhost:8080/api) and press Test connection. It does not help with Arkham: that is a separate attribution service with its own key and quota that cannot be hosted, and Hopline only asks it about a wallet when you ask. What it costs: Bitcoin Core plus Esplora's index. The electrs README gives roughly 440 GB for the index after compaction and about 1 TB free during the first indexing (light mode needs less but is slower), on top of Bitcoin Core's own data, and the first sync takes a day or more; check the current Esplora and electrs documentation before you size a machine. Things to know: Hopline opened from a file or another address needs the server to allow cross-origin requests (Access-Control-Allow-Origin: *, which a reverse proxy can add; Test connection tells you if it does not), an https:// page cannot call a plain http:// server, and a plain Esplora has no price service, so under Fiat prices from choose mempool.space (only a currency and dates are sent, no address or transaction id), nowhere, or my server if it is a mempool.space backend (whether a self-hosted mempool backend serves price history was not confirmed).

Data source. By default the page asks mempool.space directly from your browser, which lets mempool.space see your IP address and what you look up. mempool.space over Tor (.onion) sends the same requests to the mempool.space onion service instead (fewer parallel requests, more spacing, longer timeout): open the page in Tor Browser for this, since an ordinary browser cannot reach .onion addresses, and note that a browser may refuse a request from an https:// page to an http:// onion address, so open the file from disk or from http://localhost. You can also point it at your own Esplora-compatible API (it must allow cross-origin requests). The page makes no other network requests: no fonts, analytics or CDNs.