Get Token Bubble Map - Bubblemaps B2B

GET

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
  },
  "metrics": {
    "supply_stats": {
      "cexs": 123,
      "dexs": 123,
      "contracts": 123,
      "fresh_wallets": 123,
      "top_10_adjusted": 123,
      "bundles": 123
    },
    "scores": {
      "bubblemaps_score": 123,
      "gini_index": 123,
      "herfindahl_hirschman_index": 123,
      "nakamoto_coefficient": 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
      }
    ],
    "time_nodes": [
      {
        "address": "<string>",
        "relationships": [
          {
            "from_address": "<string>",
            "to_address": "<string>",
            "data": {
              "total_value": 123,
              "total_transfers": 123,
              "first_date": 123,
              "last_date": 123,
              "token_key": {
                "address": "<string>"
              }
            },
            "rel_type": "GROUPED_TRANSFER"
          }
        ]
      }
    ]
  },
  "relationships": [
    {
      "from_address": "<string>",
      "to_address": "<string>",
      "data": {
        "total_value": 123,
        "total_transfers": 123,
        "first_date": 123,
        "last_date": 123,
        "token_key": {
          "address": "<string>"
        }
      },
      "rel_type": "GROUPED_TRANSFER"
    }
  ],
  "clusters": [
    {
      "share": 123,
      "amount": 123,
      "holder_count": 123,
      "holders": [
        "<string>"
      ]
    }
  ]
}

Credit cost: 25 per request.

Response fields decentralization_score and identified_supply are deprecated, use metrics instead. See the changelog.

Get all the map data (holders, transfers, clusters, metrics, 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 computed and used in the relationships, score, and clusters. Disable with use_magic_nodes=false.
By default, time nodes are computed and used in the relationships, score, and clusters. Disable with use_time_nodes=false.
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)

Option	Credits
Base request	25
`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).
metrics include various scores and stats described in detail in the metrics endpoint documentation.

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

Time Nodes

Bubblemaps 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,

hyperevm,

arbitrum

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

use_time_nodes

boolean

default:true

return_nodes

boolean

default:false

return_relationships

boolean

default:false

return_clusters

boolean

default:true

Response

Successful Response

metadata

MapMetadataV0 · object

required

Show child attributes

metrics

MapMetricsV0 · object

required

Show child attributes

nodes

NodesDataV0 · object

Show child attributes

relationships

GroupedTransferV0 · object[] | null

Show child attributes

clusters

ClusterData · object[] | null

Show child attributes

Get Token Metrics

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
  },
  "metrics": {
    "supply_stats": {
      "cexs": 123,
      "dexs": 123,
      "contracts": 123,
      "fresh_wallets": 123,
      "top_10_adjusted": 123,
      "bundles": 123
    },
    "scores": {
      "bubblemaps_score": 123,
      "gini_index": 123,
      "herfindahl_hirschman_index": 123,
      "nakamoto_coefficient": 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
      }
    ],
    "time_nodes": [
      {
        "address": "<string>",
        "relationships": [
          {
            "from_address": "<string>",
            "to_address": "<string>",
            "data": {
              "total_value": 123,
              "total_transfers": 123,
              "first_date": 123,
              "last_date": 123,
              "token_key": {
                "address": "<string>"
              }
            },
            "rel_type": "GROUPED_TRANSFER"
          }
        ]
      }
    ]
  },
  "relationships": [
    {
      "from_address": "<string>",
      "to_address": "<string>",
      "data": {
        "total_value": 123,
        "total_transfers": 123,
        "first_date": 123,
        "last_date": 123,
        "token_key": {
          "address": "<string>"
        }
      },
      "rel_type": "GROUPED_TRANSFER"
    }
  ],
  "clusters": [
    {
      "share": 123,
      "amount": 123,
      "holder_count": 123,
      "holders": [
        "<string>"
      ]
    }
  ]
}

​Parameters

​Response

Magic Nodes

Time Nodes

Bubblemaps Score

​Query Duration

Authorizations

Path Parameters

Query Parameters

Response

Parameters

Response

Query Duration