Skip to main content
GET
/
v0
/
tokens
/
map
/
{chain}
/
{token_address}
Get Token Map
curl --request GET \
  --url https://api.bubblemaps.io/v0/tokens/map/{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": {
          "degree": 123,
          "is_supernode": true,
          "is_contract": true,
          "is_cex": true,
          "is_dex": true,
          "inward_relations": 123,
          "outward_relations": 123,
          "label": "<string>",
          "entity_id": "<string>",
          "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": {
          "degree": 123,
          "is_supernode": true,
          "is_contract": true,
          "is_cex": true,
          "is_dex": true,
          "inward_relations": 123,
          "outward_relations": 123,
          "label": "<string>",
          "entity_id": "<string>",
          "first_activity_date": "2023-11-07T05:31:56Z"
        },
        "is_shown_on_map": true
      }
    ]
  },
  "relationships": [
    {
      "from_address": "<string>",
      "to_address": "<string>",
      "data": {
        "total_value": 123,
        "total_transfers": 123,
        "first_date": 123,
        "last_date": 123,
        "token_key": {
          "chain": "eth",
          "address": "<string>"
        }
      },
      "rel_type": "GROUPED_TRANSFER"
    }
  ],
  "decentralization_score": 123,
  "clusters": [
    {
      "share": 123,
      "amount": 123,
      "holder_count": 123,
      "holders": [
        "<string>"
      ]
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.bubblemaps.io/llms.txt

Use this file to discover all available pages before exploring further.

Credit cost: 25 per request.
Get all the map data (holders, transfers, clusters, decentralisation score, etc) for a given token.
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.
You’ll find the parameters and response schemas at the end of this page, but here’s some additional context:

​
Parameters

  • The base map includes the top 80 holders of the token. This is the same as the iFrame integrations. You can change the number of holders with the limit parameter.
  • By default, magic nodes are fetched and considered in the relationships, score, and clusters computation. You can change that with the use_magic_nodes query parameter.
  • The return_* query parameters define what is returned in the response. To ensure lightweight responses, only return the data you actually use! The parameter return_nodes includes the list of nodes and their labels and metadata.
  • Data can be cached for performance, cache TTL depends on token age. Date of update can be found in the X-Dt-Update response header. If you need to force a refresh, you can use the refresh=true query param.
  • History mode: to access the state of a map in a specific date in the past, use the timestamp parameter (unix timestamp)
OptionCredits
Base request25
limit=250+50
limit=500+100
return_nodes=true+25
refresh=true+25
timestamp=XXX+50

​
Response

  • 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 GROUPED_TRANSFER relationship object (other types of relationships with different data schemas will be supported in the future, make sure this doesn’t break your typing).
  • 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.
If you are using the relationships data, beware of the token_key.chain type. It is an Enum, but additional chains will be supported in the future, without notice. Make sure that it won’t break your typing.

Magic Nodes

Decentralization Score

​
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.

Authorizations

​
X-ApiKey
string
header
required

Path Parameters

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

Query Parameters

​
limit
enum<integer>
default:80
Available options:
80,
250,
500
​
timestamp
integer | null
​
refresh
boolean
default:false
​
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
MapMetadataV0 · object
required
​
nodes
NodesDataV0 · object
​
relationships
GroupedTransferV0 · object[] | null
​
decentralization_score
number | null
​
clusters
ClusterData · object[] | null