# Bubble map

> The top holders (top, up to 500) as nodes and the links between them as edges: funding between holders, token transfers between holders, and funders shared by…

Source: https://docs.crius.sh/reference/wallet-graph/bubble-map/ · Updated 2026-10-28

GET https://api.crius.sh/v1/{chain}/token/{address}/bubblemap

The top holders (`top`, up to 500) as nodes and the links between them as edges: funding between holders, token transfers between holders, and funders shared by two or more of them. Each cluster lists its members and why they are linked (`links`: shared funders, funding and transfers between them).

Only real holders are on the map. Pools, the Uniswap V4 PoolManager, LP lockers, hooks, burn addresses, routers, other contracts and exchanges are listed under `hidden_infra` with their share. Funding from exchanges, bridges and app relayers (one signer paying the same 100+ wallets again and again) never links wallets, and dust sends from lookalike addresses (address poisoning) are ignored. `include=infra,hubs,funders` brings infrastructure, hub funding and single-wallet funders back. Pass `block` for a historical map. Ready to render with any force-directed graph library.

> Nodes = holders (+ funders shared by 2+ of them), edges = funding / transfers / common funders; clusters with the links that make them. Infrastructure (pools, PoolManager, lockers, hooks, burn, routers, contracts, exchanges) is listed under hidden\_infra, not on the map.

## Path parameters

`chain`stringrequired

Chain slug (`robinhood`) or chain id (`4663`).

`address`stringrequired

Contract or wallet address, any case (`0x…`, 20 bytes).

## Query parameters

`top`integer Default `100`

Number of top holders to include as nodes. Up to 500.

`edges`string Default `funding,transfers,common_funder`

Which links to include between holders.

`include`string

Comma list of hidden classes to bring back: `infra` (pools, PoolManager, lockers, hooks, burn, routers, contracts, exchanges), `hubs` (funding from exchanges, bridges, relayers), `funders` (external funders of a single wallet). Infra | hubs | funders (comma-separated)

`block`integer

Build the map as of this block (historical).

## Guides that use this endpoint

[**Get the holders of a Robinhood Chain token (token holders API)**Robinhood Chain token holders API: get any token's top holders in one call, with balance, share of supply, USD value, labels, holder count and top-10 share.](https://docs.crius.sh/guides/get-token-holders/)[**Read a token's bubble map and holder clusters**Get a Robinhood Chain token's top holders as a graph, with the funding and transfer links that group them. Real examples, with and without clusters.](https://docs.crius.sh/guides/read-a-bubble-map/)[**Find wallets connected by funding**Find who funded a Robinhood Chain wallet, which wallets it funded, who it swaps tokens with and who shares its funder, to spot alt wallets, dev links, sybils.](https://docs.crius.sh/guides/find-connected-wallets/)[**Robinhood Chain API for risk and compliance**Screen Robinhood Chain tokens and wallets with the Crius API: security checks, insider launches, funding links, developer history and LP locks.](https://docs.crius.sh/use-cases/risk-and-compliance/)

## Errors

Errors come back as `{ "error": { "code", "message" } }` with the matching HTTP status: `400` bad parameter, `401` missing or invalid key, `403` endpoint above your plan, `404` unknown token or address, `429` rate limit or credits used up (with `Retry-After`). See [Errors](https://docs.crius.sh/errors/).

## More bundles & bubble maps endpoints

[GET/token/{address}/bundlesSnipers, bundles & clustersStarter · 10 cr](https://docs.crius.sh/reference/wallet-graph/snipers-bundles-clusters/)

Request Needs a Starter key

 

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0xddccd4690cc99cf19d2e0bdbcb390d17e913958a/bubblemap?top=50" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0xddccd4690cc99cf19d2e0bdbcb390d17e913958a/bubblemap?top=50", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0xddccd4690cc99cf19d2e0bdbcb390d17e913958a/bubblemap?top=50",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

Response 200 · captured Oct 28, 2026

```json
{
  "data": {
    "block": null,
    "clusters": [],
    "edges": [],
    "hidden_infra": [
      {
        "address": "0x8366a39cc670b4001a1121b8f6a443a643e40951",
        "label": "uniswap_v4_pool_manager",
        "pct": 22.2145,
        "tags": [
          "pool"
        ]
      },
      {
        "address": "0x267444d099b10fb5ed7c3cc7b7c767adca574952",
        "label": "pons_v2_launch_locker",
        "pct": 8.16327,
        "tags": [
          "lp_locker"
        ]
      },
      {
        "address": "0xe5e702641ea86f4ae6cc3cdaed2b886f976be044",
        "label": "pons_v2_meme_hook",
        "pct": 6.06241,
        "tags": [
          "launchpad"
        ]
      },
      {
        "address": "0xbe0b139abc90723af76a89d3051f60ba1b64c8d9",
        "label": null,
        "pct": 1,
        "tags": [
          "contract"
        ]
      },
      {
        "address": "0xdead000000000000000000000000000000000000",
        "label": null,
        "pct": 0.81637,
        "tags": [
          "burn"
        ]
      },
      {
        "address": "0x0afeb98a5b40bc38e9cf5a3f202c17843a7ce553",
        "label": null,
        "pct": 0.168848,
        "tags": [
          "contract"
        ]
      }
    ],
    "nodes": [
      {
        "cluster": null,
        "id": "0xe1a5961d61200006577f2e96114d212889213cd6",
        "label": null,
        "pct": 2.82829,
        "tags": [
          "smart_account",
          "whale"
        ],
        "value_usd": 1286.54
      },
      {
        "cluster": null,
        "id": "0xa4109b8d391723d8f6bcfc5d75e6996f61062f76",
        "label": null,
        "pct": 2.70423,
        "tags": [
          "smart_account",
          "fomo",
          "whale"
        ],
        "value_usd": 1230.11
      },
      {
        "cluster": null,
        "id": "0xf2caeb616fb22a8acc00afbaeee83b24f18b354b",
        "label": null,
        "pct": 2.23269,
        "tags": [
          "smart_account",
          "fomo",
          "whale"
        ],
        "value_usd": 1015.61
      },
      {
        "cluster": null,
        "id": "0xb9b642020e216e84887ad414e067928e380bbbd5",
        "label": null,
        "pct": 1.77186,
        "tags": [
          "whale"
        ],
        "value_usd": 805.992
      },
      {
        "cluster": null,
        "id": "0xc9cafef2258a07f8455da92438360318b34848e2",
        "label": null,
        "pct": 1.73578,
        "tags": [
          "smart_account",
          "fomo",
          "whale"
        ],
        "value_usd": 789.58
      },
      {
        "cluster": null,
        "id": "0xc51c3340b898a67fed7c9f18db75b346dd04f8a0",
        "label": null,
        "pct": 1.63331,
        "tags": [
          "smart_account",
          "fomo",
          "whale"
        ],
        "value_usd": 742.968
      }
    ],
    "token": "0xddccd4690cc99cf19d2e0bdbcb390d17e913958a"
  },
  "meta": {
    "block": 100406890,
    "block_age_ms": 885,
    "block_ts": 1793225087000,
    "chain": "robinhood",
    "finalized_block": 100397649,
    "lag_ms": 30,
    "safe_block": 100401329
  }
}
```

[Get a key for this endpoint](https://dashboard.crius.sh/signup?ref=docs-endpoint) [Report an issue](mailto:support@crius.sh?subject=Docs%20issue%3A%20GET%20%2Fv1%2F%7Bchain%7D%2Ftoken%2F%7Baddress%7D%2Fbubblemap&body=Page%3A%20https%3A%2F%2Fdocs.crius.sh%2Freference%2Fwallet-graph%2Fbubble-map%2F%0A%0AWhat's%20wrong%20or%20missing%3F%0A%0A)