# 🪙 coinexplorer

# The self-hosted, zero-API-key explorer for stablecoins & major crypto

Live at www.coinexplorer.io

The BTC/ETH badges above are rendered from this platform's own live API.

# What is this?

A complete blockchain explorer platform built from scratch — indexer, API, and dashboard — that reads raw JSON-RPC/REST from free public endpoints only. No Etherscan keys, no Infura, no paid data vendors. Point it at the internet and it indexes:

• 💵 11 stablecoins — USDT, USDC, DAI/USDS, USDe, FDUSD, PYUSD, RLUSD, USDG, TUSD, USDB — across every chain they live on
• 🚀 Major crypto — WETH, WBTC, LINK, UNI, AAVE, SHIB, PEPE, ARB, OP, BONK, JUP, WIF and more, valued at live prices
• 🐋 Native-coin whales — large BTC, ETH, BNB, AVAX, POL, TRX and SOL transfers, straight from full blocks

Four chain families, one canonical event:

Everything lands in one schema: {chain, block, tx_hash, timestamp, token, from, to, amount, decimals} — so the API, WebSocket stream, and dashboard are chain-agnostic.

# 📊 The numbers

# ✨ The platform

• 8-page responsive app (desktop → smartphone): market overview, per-token analytics, per-chain explorer, transfer browser, whale watch, issuance flows, address & tx views, infra status
• Real charts — hand-rolled SVG line charts with crosshair tooltips, diverging issuance columns, magnitude bars; colorblind-validated palette, native dark mode
• Crypto icons everywhere — real logos with brand-colored generated fallbacks (no broken images, no tracking)
• Live WebSocket feed — wss://…/v1/stream/transfers pushes every transfer above your USD floor
• Interactive API docs — 22 endpoints with in-page Try it consoles that execute against the live instance, plus OpenAPI at /docs
• Signals stablecoin holders actually want: net issuance (mints − burns) per token, on-chain supply history per chain, native vs bridged tagging, discontinued-asset flags, whale rankings

# 🏗 Architecture

flowchart LR
    subgraph rpcs [Free public RPCs — no keys]
      EVM[21 EVM chains]
      TRON[TronGrid]
      SOL[Solana]
      BTC[esplora REST]
    end
    subgraph indexer [Indexer — one watchdogged thread per chain]
      POOL[RpcPool / RestPool<br/>token bucket · health EMA · failover]
      AD[4 family adapters<br/>canonical event out]
      WORK[Workers: prices · supply<br/>whale extraction · rolling aggregates]
    end
    DB[(SQLite WAL / PostgreSQL<br/>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

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

# 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)

# 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

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.