Skip to main content
GET
/
maps
/
{chain}
/
{token_address}
Get Map Data
curl --request GET \
  --url https://api.bubblemaps.io/maps/{chain}/{token_address} \
  --header 'X-ApiKey: <api-key>'
{
  "metadata": {
    "dt_update": "<string>",
    "ts_update": 123,
    "identified_supply": {
      "share_in_cexs": 123,
      "share_in_dexs": 123,
      "share_in_other_contracts": 123
    }
  },
  "nodes": {
    "top_holders": [
      {
        "address": "<string>",
        "address_details": {
          "label": "<string>",
          "degree": 123,
          "is_supernode": true,
          "is_contract": true,
          "is_cex": true,
          "is_dex": true,
          "entity_id": "<string>",
          "inward_relations": 123,
          "outward_relations": 123,
          "first_activity_date": "2023-11-07T05:31:56Z"
        },
        "holder_data": {
          "amount": 123,
          "rank": 123,
          "share": 123
        },
        "is_shown_on_map": true
      }
    ],
    "magic_nodes": [
      {
        "address": "<string>",
        "address_details": {
          "label": "<string>",
          "degree": 123,
          "is_supernode": true,
          "is_contract": true,
          "is_cex": true,
          "is_dex": true,
          "entity_id": "<string>",
          "inward_relations": 123,
          "outward_relations": 123,
          "first_activity_date": "2023-11-07T05:31:56Z"
        },
        "is_shown_on_map": true
      }
    ]
  },
  "relationships": [
    {
      "from_address": "<string>",
      "to_address": "<string>",
      "rel_type": "GROUPED_TRANSFER",
      "data": {
        "total_value": 123,
        "total_transfers": 123,
        "first_date": 123,
        "last_date": 123,
        "token_ref": {
          "chain": "eth",
          "address": "<string>"
        }
      }
    }
  ],
  "decentralization_score": 123,
  "clusters": [
    {
      "share": 123,
      "amount": 123,
      "holder_count": 123,
      "holders": [
        "<string>"
      ]
    }
  ]
}
This is where you get all the interesting map data. You just have to provide:
  • The token chain and address, through path parameters. If you provide a non-public chain, you’ll get a 400 error (see Get Supported Chains).
  • Whether you want to use magic nodes or not, through the use_magic_nodes query parameter. If you do, magic nodes will be fetched and considered in the relationships, score, and clusters computation.
  • What data you want to be returned in your response, through the return_* query parameters described below. To ensure lightweight responses, only return the data you actually use!
All tokens are supported by default, including NFT collections, but beware of errors: a 404 will be returned if no holders are found, and a 400 might be returned for some rare unsupported tokens.

​
Query Duration

Query duration ranges from a few ms for cache hits, up to a minute for outliers. Most queries should not take more than 15s though.
Using magic nodes will increase the duration of the query.

​
Response Format

See the expected schema at the end of this page, but here’s some additional context:
  • The base nodes list is the top 80 holders of the token. This is aligned with the iFrame integrations. This number might change in the future.
  • All share values are in [0, 1] format, meaning 42% will be returned as 0.42.
  • In the nodes lists, you’ll find a is_shown_on_map boolean. It is based on the default visibility state on our main app, meaning that CEXs, DEXs, Contracts, and hypernodes (more than 200k transfers) are hidden. These nodes are not considered in the relationships, score, and clusters computation.
  • The is_supernode boolean means that the node has a high volume of transfers (threshold may vary). Relationships between two supernodes are ignored (relationships between a supernode and a non-supernode are included though).
  • In the relationships list, transfers are grouped based on the (from_address, to_address, token_ref) key. Meaning that if A sends some BMT to B multiple times, these transfers will be grouped as a unique relationship object.
  • In some instances, the decentralization_score can be null even if you asked for it. (This means the score is not applicable on that map)
Returning nodes and relationships on dense maps might crash the API playground web interface. In these cases, don’t hesitate to try out calls directly via curl or your favorite language.

Magic Nodes

Decentralization Score

Authorizations

​
X-ApiKey
string
header
required

Path Parameters

​
chain
enum<string>
required
Available options:
eth,
base,
solana,
tron,
bsc,
apechain,
ton,
polygon,
avalanche,
sonic
​
token_address
string
required

Query Parameters

​
use_magic_nodes
boolean
default:true
​
return_nodes
boolean
default:false
​
return_relationships
boolean
default:false
​
return_clusters
boolean
default:true
​
return_decentralization_score
boolean
default:true

Response

Successful Response

​
metadata
object
required
​
nodes
object | null
​
relationships
GroupedTransfer · object[] | null
​
decentralization_score
number | null
​
clusters
ClusterData · object[] | null
⌘I