# How does it work?

### Tutorial

{% embed url="<https://www.youtube.com/watch?v=co7nohtA8nA>" %}

### Search for a token

1. Select a token (name or contract address) — for example $SHIB

<figure><img src="/files/H0orx8Bpt4mVLz7IDeSY" alt=""><figcaption></figcaption></figure>

2. Explore the bubble map of $SHIB:

{% embed url="<https://drive.google.com/file/d/1ve5omzh8SY5JB8CwZ6ID96RSG87SaqRW/view?usp=sharing>" %}

* Each bubble represents a top $SHIB holder (ranks #1 to #250).
* The size of the bubble reflects the amount of $SHIB it holds.
* Links between bubbles indicate blockchain transfers.
* Large clusters (connections between multiple holders) may reveal patterns worth investigating

### What are bubbles?

When you open the bubble map of a token (e.g. UNI), it shows the 250 top holders of this token as 250 bubbles <mark style="color:yellow;">**(1)**</mark>**,&#x20;**<mark style="color:yellow;">**(2)**</mark>**.** So each bubble represents a **current** holder, and the larger the bubble, the more tokens they hold.

Some bubbles are hidden by default if they belong to contracts or exchanges since the focus is on connections between genuine holders, not contracts. You can still reveal them by clicking the eye button next to them

Note: Addresses with very high transaction volume (like hot wallets) are labeled as *Supernodes*. Some features are limited for these nodes to keep things running smoothly. For example, you can’t open the full transfer table for them, and even if two super nodes are connected, they won’t show links on the map to avoid heavy computations.

<figure><img src="/files/1oJaBVYf15L2qhbXfwVm" alt=""><figcaption></figcaption></figure>

When you click on a bubble <mark style="color:yellow;">**(4)**</mark>, a window opens displaying details about the address <mark style="color:yellow;">**(5)**</mark>

* The % of the supply it holds
* The amount of tokens
* The $ value

If the address is part of a cluster, the window also provides aggregated information about the cluster

<figure><img src="/files/jxDDQCwrkPD7Hdyw2I9h" alt=""><figcaption></figcaption></figure>

### What are links?

If two bubbles are linked, it means there has been an on-chain transfer between those holders. In V2, these transfers can involve any token and, in some cases, even cross-chain transfers. To examine a specific link and see how two holders are connected, click on the IN/OUT <mark style="color:yellow;">**(6)**</mark> menu. This will show transfer details, including all tokens transferred and the dates of the last transfer.

<figure><img src="/files/KsbOkI9qVNFbthnuuG4T" alt=""><figcaption></figcaption></figure>

If you want to filter links, click on “All Tokens” <mark style="color:yellow;">**(7)**</mark> to open the "Transfers & Tokens" menu <mark style="color:yellow;">**(8)**</mark>, where you can filter which transfers to display. By default, all transfers between holders are shown, but you can choose to display only specific token transfers (e.g. USDC, USDT, ETH, AAVE, LINK...) or a mix. You can also filter transfers by amount <mark style="color:yellow;">**(9)**</mark>, showing only those above or below a certain $ value.

<figure><img src="/files/ViEg8f4mLBHax3YtdCE2" alt=""><figcaption></figcaption></figure>

So when bubbles are linked and form clusters, it means they have sent funds to each other. And if they’re connected, the key question is—why? Is it an employer paying an employee, a VC receiving tokens, or someone trying to cover their tracks?&#x20;

This is where the fun begins!

### What is the date of the map?

With Bubblemaps V2, we’ve worked to make the data as close to real-time as possible. When you open a bubble map, it’s guaranteed to have been refreshed within the last six hours. This ensures an up-to-date experience, though there may still be some delays, especially for newly launched tokens. You can check the exact time the map was last computed on the top island <mark style="color:yellow;">**(10)**</mark>. And with Bubblemaps V2, you can also rewind and explore past token distributions using the Time Travel feature (see dedicated tab).

<figure><img src="/files/Qg2i2GN4hQzKidJjtIaE" alt=""><figcaption></figcaption></figure>

### How to share a bubble map?

If you want to share your bubble map with others, use the permalink button <mark style="color:yellow;">**(11)**</mark>. This will share the map exactly as you see it on your screen. Any adjustments—like enabling Magic Nodes, filtering transfers, changing dates, or adding/hiding addresses—will be saved and included in the link. If you haven’t made any changes and just want to share the default bubble map, simply copy the URL. This will display the standard map without any custom settings.

To export all the addresses from a bubble map—including Magic Nodes or manually added ones—use the export button <mark style="color:yellow;">**(12)**</mark> to download them as a spreadsheet.

<figure><img src="/files/0OeOXudWOLUurKT66nwV" alt=""><figcaption></figcaption></figure>

### What type of nodes are shown on a bubble map?

A bubble map is made of different types of nodes. Some are actual token holders, while others are added to make the map easier to understand. Each node can have one or more tags that explain what it represents.

#### **Node role**

* <mark style="color:$success;">`Holder`</mark>: an address that currently owns part of the token supply shown on the map. These are the main nodes of a bubble map.
* <mark style="color:$success;">`Magic Node`</mark>: a suggested address that is not a holder, but helps reveal hidden links between holders. Magic Nodes can make clusters easier to understand by showing an intermediate address that connects wallets which would otherwise appear unrelated. See the Magic Nodes section for more details. [More here](https://wiki.bubblemaps.io/bubblemaps-v2/magic-nodes)
* <mark style="color:$success;">`Time Node`</mark>: a suggested node that reveals wallets with coordinated timing. It can help show when several wallets were funded, created, or activated around the same time. See the Time Nodes section for more details. [More here](https://wiki.bubblemaps.io/bubblemaps-v2/time-nodes)
* <mark style="color:$success;">`Manually Added`</mark>: an address added by the user during analysis. This is useful when you want to test a specific address, follow an external lead, or add a wallet that is not shown automatically.

#### **Wallet type**

* <mark style="color:$warning;">`EOA`</mark>: a regular wallet address controlled by a private key. Most individual wallets are EOAs. They can hold tokens, receive funds, trade on DEXs, or interact with contracts.
* <mark style="color:$warning;">`Contract`</mark>: a smart contract address deployed onchain. Contracts can be token contracts, vesting contracts, multisigs, routers, bridges, or protocol addresses. Unlike EOAs, they are controlled by code rather than a private key.
* <mark style="color:$warning;">`CEX`</mark>: an address linked to a centralized exchange. These addresses are usually used for deposits, withdrawals, custody, or exchange operations. They often interact with many unrelated wallets, so they can create large connections on the map.
* <mark style="color:$warning;">`DEX`</mark>: an address linked to a decentralized exchange or liquidity protocol. These can include pools, routers, or other contracts used for onchain trading. DEX addresses are separated from regular contracts because they usually represent trading activity.

#### **Tags**

* <mark style="color:$primary;">`Fresh`</mark>: a newly funded address with little or no previous onchain activity. Fresh wallets are often important in investigations because coordinated actors may create new wallets before buying, receiving, or moving tokens.
* <mark style="color:$primary;">`Supernode`</mark>: a high-activity address with a large number of transfers. Supernodes are often exchanges, routers, bridges, services, or very active wallets. They can be useful, but they can also create noisy connections because many unrelated wallets interact with them.
* <mark style="color:$primary;">`Transfers`</mark>: the total number of transfers involving an address, including incoming and outgoing transfers. This number is unfiltered, meaning it reflects all transfers for that address, not only transfers related to the token shown on the map.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.bubblemaps.io/bubblemaps-v2/how-does-it-work.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.