Analytics·EVM · Solana · Multi-chain
Bubblemaps
On-chain intelligence layer that visualizes token holders as bubbles and surfaces wallet clusters likely controlled by the same entity (insider, team, whale, sybil). Ships an embeddable iframe widget (used by CoinGecko, DexScreener) and a REST Data API for holders, transfers, clusters, and bubble maps across 10+ chains.
- 01token holder distribution charts
- 02insider / whale cluster detection
- 03trust signals on token launches
- 04rug-pull and sybil-risk checks
- 05embedding visual onchain intelligence in dashboards / bots
| Variable | Scope | Description |
|---|---|---|
| BUBBLEMAPS_API_KEY | Server | Bubblemaps Data API key (Beta) from the Bubblemaps team. Server-side only — sent as the `Authorization` / `x-api-key` header per the OpenAPI spec at https://docs.bubblemaps.io/openapi.json. |
Two integration modes. (1) iFrame widget — easiest, used by CoinGecko: `<iframe src='https://app.bubblemaps.io/${chain}/token/${contractAddress}' width='100%' height='600' frameborder='0' allowfullscreen></iframe>` where `chain` is one of `eth`, `bsc`, `ftm`, `avax`, `cro`, `arbi`, `poly`, `base`, `sol`, `sonic`. Your domain MUST be whitelisted by Bubblemaps before the iframe will render (localhost / 0.0.0.0 work for dev). Use `https://api-legacy.bubblemaps.io/map-availability?chain=${chain}&token=${address}` to check whether a map exists before rendering. (2) Data API (Beta) — REST at `https://api.bubblemaps.io/v0` with key auth: `GET /v0/chains` (supported chains), `GET /v0/tokens/{chain}/{address}/map` (holders + cluster edges as JSON), `GET /v0/tokens/{chain}/{address}/holders`, `GET /v0/tokens/{chain}/{address}/transfers`, `GET /v0/addresses/{chain}/{address}` (metadata + cluster id). Use the Data API when you need raw holder graphs to feed into your own visualization.
- ⚑Wallet clustering is heuristic, not ground truth — Bubblemaps groups addresses by transfer-graph proximity and timing; it's strong evidence of co-control but never legal proof. Surface it as a 'risk signal' in UI, not as 'this is the same person'.
- ⚑iframe whitelisting: production embeds will silently fail on non-whitelisted domains — submit your domain to Bubblemaps support before launch (localhost is allowed by default for development).
- ⚑Map availability is sparse — many small-cap tokens simply don't have a map computed yet. Always pre-check via `map-availability` and gracefully fall back to a 'not available' state rather than rendering an empty iframe.
- ⚑Sybil/insider detection is heuristic and time-windowed — recent CEX deposits, contract calls, or routing through mixers can split clusters that are actually one entity (false negative) or merge unrelated wallets (false positive).
- ⚑Data API is in Beta — endpoint shapes and rate limits can change without semver guarantees; pin to the `/v0` path and validate response shape defensively.
- ⚑PII / privacy: a 'cluster' label associated to a wallet is a deanonymization signal. Don't expose another user's cluster ID/label in your UI without their consent; for B2C dashboards display only the connected user's own cluster.