> ## 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.
# Get Token Bubble Map
**Credit cost:** 25 per request.
Response fields `decentralization_score` and `identified_supply` are
deprecated, use `metrics` instead. See the
[changelog](/data/api/changelog/2026-05-22).
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](https://wiki.bubblemaps.io/bubblemaps-v2/magic-nodes) are computed and used in the relationships, score, and clusters. Disable with `use_magic_nodes=false`.
* By default, [time nodes](https://wiki.bubblemaps.io/bubblemaps-v2/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).
* The `is_paid_label` boolean indicates whether the label is a [community-submitted label](https://wiki.bubblemaps.io/bubblemaps-v2/submit-labels).
* 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](/data/api/tokens/metrics#response).
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.
### 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.
## OpenAPI
````yaml GET /v0/tokens/map/{chain}/{token_address}
openapi: 3.1.0
info:
title: Bubblemaps Data API
version: 0.2.2
servers:
- url: https://api.bubblemaps.io
security: []
paths:
/v0/tokens/map/{chain}/{token_address}:
get:
tags:
- v0
summary: Get Token Map
operationId: get_token_map_v0_tokens_map__chain___token_address__get
parameters:
- name: chain
in: path
required: true
schema:
$ref: '#/components/schemas/ChainIdV0'
- name: token_address
in: path
required: true
schema:
type: string
title: Token Address
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/HoldersLimit'
default: 80
- name: timestamp
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
ge: 0
title: Timestamp
- name: refresh
in: query
required: false
schema:
type: boolean
title: If true, bypass cache and force a refresh to latest data.
default: false
- name: use_magic_nodes
in: query
required: false
schema:
type: boolean
title: >-
If true, use magic nodes in map computation and include them in
the response.
default: true
- name: use_time_nodes
in: query
required: false
schema:
type: boolean
title: >-
If true, compute time nodes (temporal groupings of transfers
through CEX/DEX/whitelisted contracts) and include them in the
cluster computation.
default: true
- name: return_nodes
in: query
required: false
schema:
type: boolean
default: false
title: Return Nodes
- name: return_relationships
in: query
required: false
schema:
type: boolean
default: false
title: Return Relationships
- name: return_clusters
in: query
required: false
schema:
type: boolean
default: true
title: Return Clusters
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MapDataV0'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
ChainIdV0:
type: string
enum:
- eth
- base
- solana
- tron
- bsc
- sonic
- ton
- avalanche
- polygon
- monad
- hyperevm
- arbitrum
- robinhood
title: ChainIdV0
HoldersLimit:
type: integer
enum:
- 80
- 250
- 500
title: HoldersLimit
MapDataV0:
properties:
metadata:
$ref: '#/components/schemas/MapMetadataV0'
metrics:
$ref: '#/components/schemas/MapMetricsV0'
nodes:
anyOf:
- $ref: '#/components/schemas/NodesDataV0'
- type: 'null'
relationships:
anyOf:
- items:
$ref: '#/components/schemas/GroupedTransferV0'
type: array
- type: 'null'
title: Relationships
clusters:
anyOf:
- items:
$ref: '#/components/schemas/ClusterData'
type: array
- type: 'null'
title: Clusters
type: object
required:
- metadata
- metrics
title: MapDataV0
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
MapMetadataV0:
properties:
dt_update:
type: string
title: Dt Update
ts_update:
type: integer
title: Ts Update
type: object
required:
- dt_update
- ts_update
title: MapMetadataV0
MapMetricsV0:
properties:
supply_stats:
$ref: '#/components/schemas/SupplyStatsV0'
scores:
$ref: '#/components/schemas/MapScoresV0'
type: object
required:
- supply_stats
- scores
title: MapMetricsV0
NodesDataV0:
properties:
top_holders:
items:
$ref: '#/components/schemas/AccountAddressWithHolderDataWithMapContextV0'
type: array
title: Top Holders
magic_nodes:
anyOf:
- items:
$ref: '#/components/schemas/AccountAddressWithDetailsWithMapContextV0'
type: array
- type: 'null'
title: Magic Nodes
time_nodes:
anyOf:
- items:
$ref: '#/components/schemas/TimeNodeV0'
type: array
- type: 'null'
title: Time Nodes
type: object
required:
- top_holders
title: NodesDataV0
GroupedTransferV0:
properties:
from_address:
type: string
title: From Address
to_address:
type: string
title: To Address
rel_type:
type: string
const: GROUPED_TRANSFER
title: Rel Type
default: GROUPED_TRANSFER
data:
$ref: '#/components/schemas/GroupedTransferDataV0'
type: object
required:
- from_address
- to_address
- data
title: GroupedTransferV0
ClusterData:
properties:
share:
type: number
title: Share
amount:
type: number
title: Amount
holder_count:
type: integer
title: Holder Count
holders:
items:
type: string
type: array
title: Holders
type: object
required:
- share
- amount
- holder_count
- holders
title: ClusterData
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
SupplyStatsV0:
properties:
cexs:
type: number
title: Cexs
dexs:
type: number
title: Dexs
contracts:
type: number
title: Contracts
fresh_wallets:
type: number
title: Fresh Wallets
top_10_adjusted:
type: number
title: Top 10 Adjusted
bundles:
type: number
title: Bundles
type: object
required:
- cexs
- dexs
- contracts
- fresh_wallets
- top_10_adjusted
- bundles
title: SupplyStatsV0
MapScoresV0:
properties:
bubblemaps_score:
type: number
title: Bubblemaps Score
gini_index:
type: number
title: Gini Index
herfindahl_hirschman_index:
type: number
title: Herfindahl Hirschman Index
nakamoto_coefficient:
type: integer
title: Nakamoto Coefficient
type: object
required:
- bubblemaps_score
- gini_index
- herfindahl_hirschman_index
- nakamoto_coefficient
title: MapScoresV0
AccountAddressWithHolderDataWithMapContextV0:
properties:
address:
type: string
title: Address
address_details:
$ref: '#/components/schemas/AccountAddressDetails'
holder_data:
$ref: '#/components/schemas/HolderData'
is_shown_on_map:
type: boolean
title: Is Shown On Map
type: object
required:
- address
- address_details
- holder_data
- is_shown_on_map
title: AccountAddressWithHolderDataWithMapContextV0
AccountAddressWithDetailsWithMapContextV0:
properties:
address:
type: string
title: Address
address_details:
$ref: '#/components/schemas/AccountAddressDetails'
is_shown_on_map:
type: boolean
title: Is Shown On Map
type: object
required:
- address
- address_details
- is_shown_on_map
title: AccountAddressWithDetailsWithMapContextV0
TimeNodeV0:
properties:
address:
type: string
title: Address
relationships:
items:
$ref: '#/components/schemas/GroupedTransferV0'
type: array
title: Relationships
type: object
required:
- address
- relationships
title: TimeNodeV0
GroupedTransferDataV0:
properties:
total_value:
type: number
title: Total Value
total_transfers:
type: integer
title: Total Transfers
first_date:
type: integer
title: First Date
last_date:
type: integer
title: Last Date
token_key:
$ref: '#/components/schemas/TokenKey'
type: object
required:
- total_value
- total_transfers
- first_date
- last_date
- token_key
title: GroupedTransferDataV0
AccountAddressDetails:
properties:
label:
anyOf:
- type: string
- type: 'null'
title: Label
degree:
type: integer
title: Degree
is_supernode:
type: boolean
title: Is Supernode
is_contract:
type: boolean
title: Is Contract
is_cex:
type: boolean
title: Is Cex
is_dex:
type: boolean
title: Is Dex
is_paid_label:
type: boolean
title: Is Paid Label
default: false
entity_id:
anyOf:
- type: string
- type: 'null'
title: Entity Id
inward_relations:
type: integer
title: Inward Relations
outward_relations:
type: integer
title: Outward Relations
first_activity_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: First Activity Date
type: object
required:
- degree
- is_supernode
- is_contract
- is_cex
- is_dex
- inward_relations
- outward_relations
title: AccountAddressDetails
HolderData:
properties:
amount:
type: number
title: Amount
rank:
type: integer
title: Rank
share:
type: number
title: Share
type: object
required:
- amount
- rank
- share
title: HolderData
TokenKey:
properties:
chain:
$ref: '#/components/schemas/ChainIdV0'
address:
type: string
title: Address
type: object
required:
- chain
- address
title: TokenKey
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-ApiKey
````