# ๐ช coinexplorer
### The self-hosted, zero-API-key explorer for stablecoins & major crypto
**Live at [www.coinexplorer.io](https://www.coinexplorer.io)**
[](https://www.coinexplorer.io)
[](https://www.coinexplorer.io/v1/prices)
[](https://www.coinexplorer.io/v1/prices)
[](https://www.coinexplorer.io/status.html)
[](https://www.coinexplorer.io/v1/tokens)
[](#-free-rpc-philosophy)
[](https://www.python.org)
[](https://www.coinexplorer.io/api.html)
[](tests/)
[](LICENSE)
*The BTC/ETH badges above are rendered from this platform's own live API.*
token bucket ยท health EMA ยท failover]
AD[4 family adapters
canonical event out]
WORK[Workers: prices ยท supply
whale extraction ยท rolling aggregates]
end
DB[(SQLite WAL / PostgreSQL
one codebase, both engines)]
subgraph api [FastAPI]
REST[REST /v1]
WS[WebSocket stream]
MET[Prometheus /metrics]
UI[dashboard + API docs]
end
rpcs --> POOL --> AD --> DB
POOL --> WORK --> DB
DB --> REST & WS & MET & UI
```
### Built for hostile (free) infrastructure
- **Per-endpoint token buckets** โ respect documented limits (toncenter 1 rps, Solana ~10 rps/IPโฆ) *before* getting 429'd
- **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 instead
- **Reorg safety** โ parent-hash chain-linking on every cursor advance + chain-specific confirmation depths, with automatic rollback
- **Two-cursor design** โ head-tailing always has priority; history grows *backwards* one slice per cycle (`EXPLORER_BACKFILL_DAYS`)
- **Watchdog supervisor** โ any dead worker thread is rebuilt within 30 s
- **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)
## ๐ Quickstart
```bash
git clone https://github.com/spboucher-ai/coinexplorer && cd coinexplorer
# Docker โ one command
cp .env.example .env && docker compose up -d --build
open http://localhost:8080
# Or bare metal
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python scripts/verify_tokens.py # never index an unverified address
.venv/bin/python run_indexer.py # Ctrl-C safe, resumes from cursors
.venv/bin/uvicorn api.main:app --port 8080
```
## ๐ API in 30 seconds
Full interactive reference: **[coinexplorer.io/api.html](https://www.coinexplorer.io/api.html)**
```bash
# largest transfers of the last 24h, any asset, any chain
curl "https://www.coinexplorer.io/v1/stablecoins/whales?window=24h&min_usd=10000000"
# USDC net issuance (mints โ burns), bucketed
curl "https://www.coinexplorer.io/v1/stablecoins/flows?token=USDC&window=7d"
# resolve anything: tx hash, address, symbol, chain
curl "https://www.coinexplorer.io/v1/search?q=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
# live feed
websocat "wss://www.coinexplorer.io/v1/stream/transfers?min_usd=100000"
```
## โ Add a chain in < 30 lines (EVM: config only)
```yaml
# config/chains.yaml
mynewchain:
family: evm
chain_id: 12345
block_time: 2
confirmations: 10
max_range: 150
start_offset: 1800
rpcs: [https://rpc.mynewchain.org]
```
Add its tokens to `config/tokens.yaml`, run `scripts/verify_tokens.py`
(it refuses wrong addresses and chain-ids), restart. Non-EVM families are ~150-line
adapters โ see `indexer/adapters/tron.py` as the template. **13 more chains**
(XRPL, Stellar, Noble, TON, Aptos, Sui, Algorand, Near, Tezos, Hedera, Starknet,
Polkadot, EOS) are already configured with verified identifiers, waiting for their adapters.
## ๐งช Tests
```bash
for t in tests/test_*.py; do .venv/bin/python "$t"; done
```
Four suites, 19 checks: token-bucket pacing, failover classification, getLogs range-halving
contiguity, reorg rollback, Base58Check vectors, TRC-20/SPL decoding, Bitcoin UTXO whale
semantics, EVM native extraction, price upserts.
## โ๏ธ Data honesty
Supply figures use on-chain `totalSupply()` (bridged wrappers double-count their locked
collateral โ the `native` flag lets you de-duplicate). Solana multi-sender transfers keep exact
amounts with `from: null`. Volume uses face value ร live price over the indexed window only.
Aggregates use float casts โ dashboards, not accounting. **Nothing here is financial advice.**
---
## Author
**Simon-Pierre Boucher**
๐ง [contact@spboucher.ai](mailto:contact@spboucher.ai)
Built from scratch โ every decoder, every adapter, every chart.
๐ **[www.coinexplorer.io](https://www.coinexplorer.io)**
[MIT License](LICENSE)