spb/coinexplorer Public MIT
Self-hosted, zero-API-key explorer for stablecoins and major crypto.
Python 60.3%
HTML 23.6%
JavaScript 8.1%
CSS 6.8%
SQL 1%
1<div align="center">23# 🪙 coinexplorer45### The self-hosted, zero-API-key explorer for stablecoins & major crypto67**Live at [www.coinexplorer.io](https://www.coinexplorer.io)**89[](https://www.coinexplorer.io)10[](https://www.coinexplorer.io/v1/prices)11[](https://www.coinexplorer.io/v1/prices)12[](https://www.coinexplorer.io/status.html)13[](https://www.coinexplorer.io/v1/tokens)14[](#-free-rpc-philosophy)15[](https://www.python.org)16[](https://www.coinexplorer.io/api.html)17[](tests/)18[](LICENSE)1920*The BTC/ETH badges above are rendered from this platform's own live API.*2122<img src="docs/screenshot-overview.png" alt="coinexplorer market overview" width="920">2324</div>2526---2728## What is this?2930A **complete blockchain explorer platform built from scratch** — indexer, API, and dashboard —31that reads **raw JSON-RPC/REST from free public endpoints only**. No Etherscan keys, no Infura,32no paid data vendors. Point it at the internet and it indexes:3334- 💵 **11 stablecoins** — USDT, USDC, DAI/USDS, USDe, FDUSD, PYUSD, RLUSD, USDG, TUSD, USDB — across every chain they live on35- 🚀 **Major crypto** — WETH, WBTC, LINK, UNI, AAVE, SHIB, PEPE, ARB, OP, BONK, JUP, WIF and more, valued at live prices36- 🐋 **Native-coin whales** — large BTC, ETH, BNB, AVAX, POL, TRX and SOL transfers, straight from full blocks3738**Four chain families, one canonical event:**3940| Family | Chains | How transfers are read |41|---|---|---|42| **EVM** | Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, Celo, Kaia, Ink, Scroll, Linea, Mantle, Gnosis, ZKsync, Blast, Unichain, World Chain, Sonic, Sei, HyperEVM | `eth_getLogs` + hand-rolled ABI decoding |43| **Tron** | Tron | block tx-infos + Base58Check codec written from scratch |44| **Solana** | Solana | pre/post token-balance diffs (covers Token-2022 & CPIs) |45| **Bitcoin** | Bitcoin | esplora REST, UTXO whale outputs |4647Everything lands in one schema: `{chain, block, tx_hash, timestamp, token, from, to, amount, decimals}` —48so the API, WebSocket stream, and dashboard are chain-agnostic.4950## 📊 The numbers5152| Metric | Value |53|---|---|54| Chains indexing live | **24** (13 more configured & verified, awaiting adapters) |55| Verified asset deployments | **94** — every EVM address checked on-chain (`symbol()` + `decimals()`) before indexing |56| Transfers indexed (production instance) | **20M+ and growing** |57| Hot API endpoints | **< 200 ms** at any index size (precomputed aggregates) |58| Whale detection floor | $100K, incremental — a $72M BTC move was caught minutes after boot |59| Price refresh | 40 symbols / 5 min, one keyless CoinGecko call |60| Paid API keys required | **0** |6162## ✨ The platform6364<div align="center"><img src="docs/screenshot-api.png" alt="API documentation" width="920"></div>6566- **8-page responsive app** (desktop → smartphone): market overview, per-token analytics, per-chain67 explorer, transfer browser, whale watch, issuance flows, address & tx views, infra status68- **Real charts** — hand-rolled SVG line charts with crosshair tooltips, diverging issuance columns,69 magnitude bars; colorblind-validated palette, native dark mode70- **Crypto icons everywhere** — real logos with brand-colored generated fallbacks (no broken images, no tracking)71- **Live WebSocket feed** — `wss://…/v1/stream/transfers` pushes every transfer above your USD floor72- **[Interactive API docs](https://www.coinexplorer.io/api.html)** — 22 endpoints with in-page73 *Try it* consoles that execute against the live instance, plus OpenAPI at `/docs`74- **Signals stablecoin holders actually want**: net issuance (mints − burns) per token, on-chain75 supply history per chain, native vs bridged tagging, discontinued-asset flags, whale rankings7677## 🏗 Architecture7879```mermaid80flowchart LR81 subgraph rpcs [Free public RPCs — no keys]82 EVM[21 EVM chains]83 TRON[TronGrid]84 SOL[Solana]85 BTC[esplora REST]86 end87 subgraph indexer [Indexer — one watchdogged thread per chain]88 POOL[RpcPool / RestPool<br/>token bucket · health EMA · failover]89 AD[4 family adapters<br/>canonical event out]90 WORK[Workers: prices · supply<br/>whale extraction · rolling aggregates]91 end92 DB[(SQLite WAL / PostgreSQL<br/>one codebase, both engines)]93 subgraph api [FastAPI]94 REST[REST /v1]95 WS[WebSocket stream]96 MET[Prometheus /metrics]97 UI[dashboard + API docs]98 end99 rpcs --> POOL --> AD --> DB100 POOL --> WORK --> DB101 DB --> REST & WS & MET & UI102```103104### Built for hostile (free) infrastructure105106- **Per-endpoint token buckets** — respect documented limits (toncenter 1 rps, Solana ~10 rps/IP…) *before* getting 429'd107- **Health-scored failover** — success-rate EMA + exponential cooldowns; rate limits disguised as JSON-RPC errors are detected and routed around; *"query too big"* errors trigger adaptive range halving instead108- **Reorg safety** — parent-hash chain-linking on every cursor advance + chain-specific confirmation depths, with automatic rollback109- **Two-cursor design** — head-tailing always has priority; history grows *backwards* one slice per cycle (`EXPLORER_BACKFILL_DAYS`)110- **Watchdog supervisor** — any dead worker thread is rebuilt within 30 s111- **Scale-proof reads** — whale extraction and volume/series aggregates are maintained incrementally by background workers, so no UI query ever rescans the transfers table (26 s → 2 ms, measured)112113## 🚀 Quickstart114115```bash116git clone https://github.com/spboucher-ai/coinexplorer && cd coinexplorer117118# Docker — one command119cp .env.example .env && docker compose up -d --build120open http://localhost:8080121122# Or bare metal123python3 -m venv .venv && .venv/bin/pip install -r requirements.txt124.venv/bin/python scripts/verify_tokens.py # never index an unverified address125.venv/bin/python run_indexer.py # Ctrl-C safe, resumes from cursors126.venv/bin/uvicorn api.main:app --port 8080127```128129## 🔌 API in 30 seconds130131Full interactive reference: **[coinexplorer.io/api.html](https://www.coinexplorer.io/api.html)**132133```bash134# largest transfers of the last 24h, any asset, any chain135curl "https://www.coinexplorer.io/v1/stablecoins/whales?window=24h&min_usd=10000000"136137# USDC net issuance (mints − burns), bucketed138curl "https://www.coinexplorer.io/v1/stablecoins/flows?token=USDC&window=7d"139140# resolve anything: tx hash, address, symbol, chain141curl "https://www.coinexplorer.io/v1/search?q=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"142143# live feed144websocat "wss://www.coinexplorer.io/v1/stream/transfers?min_usd=100000"145```146147## ➕ Add a chain in < 30 lines (EVM: config only)148149```yaml150# config/chains.yaml151 mynewchain:152 family: evm153 chain_id: 12345154 block_time: 2155 confirmations: 10156 max_range: 150157 start_offset: 1800158 rpcs: [https://rpc.mynewchain.org]159```160161Add its tokens to `config/tokens.yaml`, run `scripts/verify_tokens.py`162(it refuses wrong addresses and chain-ids), restart. Non-EVM families are ~150-line163adapters — see `indexer/adapters/tron.py` as the template. **13 more chains**164(XRPL, Stellar, Noble, TON, Aptos, Sui, Algorand, Near, Tezos, Hedera, Starknet,165Polkadot, EOS) are already configured with verified identifiers, waiting for their adapters.166167## 🧪 Tests168169```bash170for t in tests/test_*.py; do .venv/bin/python "$t"; done171```172173Four suites, 19 checks: token-bucket pacing, failover classification, getLogs range-halving174contiguity, reorg rollback, Base58Check vectors, TRC-20/SPL decoding, Bitcoin UTXO whale175semantics, EVM native extraction, price upserts.176177## ⚖️ Data honesty178179Supply figures use on-chain `totalSupply()` (bridged wrappers double-count their locked180collateral — the `native` flag lets you de-duplicate). Solana multi-sender transfers keep exact181amounts with `from: null`. Volume uses face value × live price over the indexed window only.182Aggregates use float casts — dashboards, not accounting. **Nothing here is financial advice.**183184---185186<div align="center">187188## Author189190**Simon-Pierre Boucher**191📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)192193Built from scratch — every decoder, every adapter, every chart.194🌐 **[www.coinexplorer.io](https://www.coinexplorer.io)**195196[MIT License](LICENSE)197198</div>199