> ## 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 Map Data

> Deprecated: use `GET /v0/tokens/map/{chain}/{token_address}` instead. This endpoint will be removed in the future.

<Warning>
  Deprecated: use `GET /v0/tokens/map/{chain}/{token_address}` instead. This
  endpoint will be removed in the future.
</Warning>

<Info>**Credit cost:** 50 per request.</Info>

This is where you get all the interesting map data.

You just have to provide:

* The token chain and address, through path parameters (see [Get Supported Chains](/data/api/chains/supported)).
* 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!

<Warning>
  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.
</Warning>

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

<Note>Using magic nodes will increase the duration of the query.</Note>

### 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)

<Note>
  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.
</Note>

<Warning>
  If you are using the relationships data, beware of the `token_ref.chain`
  (ContractTokenRef) and `token_ref.id` (NativeTokenRef) types. They are Enums,
  but additional chains and native tokens **will** be supported in the future,
  without notice. Make sure that it won't break your typing.
</Warning>

<CardGroup cols={2}>
  <Card title="Magic Nodes" icon="wand-magic-sparkles" href="https://x.com/bubblemaps/status/1858578503509086366" />

  <Card title="Decentralization Score" icon="hundred-points" href="https://bubblemaps.notion.site/Bubblemaps-Decentralization-Factor-ba767100c9534945ae390fd2467e4add" />
</CardGroup>


## OpenAPI

````yaml GET /maps/{chain}/{token_address}
openapi: 3.1.0
info:
  title: Bubblemaps Data API
  version: 0.2.2
servers:
  - url: https://api.bubblemaps.io
security: []
paths:
  /maps/{chain}/{token_address}:
    get:
      tags:
        - Maps
      summary: Get Map Data
      description: >-
        Deprecated: use `GET /v0/tokens/map/{chain}/{token_address}` instead.
        This endpoint will be removed in the future.
      operationId: get_map_data_maps__chain___token_address__get
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ChainId'
        - name: token_address
          in: path
          required: true
          schema:
            type: string
            title: Token Address
        - name: use_magic_nodes
          in: query
          required: false
          schema:
            type: boolean
            title: If true, use the magic nodes in the computation of the map.
            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
        - name: return_decentralization_score
          in: query
          required: false
          schema:
            type: boolean
            default: true
            title: Return Decentralization Score
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapData'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
        - APIKeyHeader: []
components:
  schemas:
    ChainId:
      type: string
      enum:
        - eth
        - base
        - solana
        - tron
        - bsc
        - apechain
        - ton
        - polygon
        - avalanche
        - sonic
        - hyperevm
        - monad
        - aptos
        - arbitrum
        - robinhood
      title: ChainId
    MapData:
      properties:
        metadata:
          $ref: '#/components/schemas/MapMetadata'
        nodes:
          anyOf:
            - $ref: '#/components/schemas/NodesData'
            - type: 'null'
        relationships:
          anyOf:
            - items:
                $ref: '#/components/schemas/GroupedTransfer'
              type: array
            - type: 'null'
          title: Relationships
        decentralization_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Decentralization Score
        clusters:
          anyOf:
            - items:
                $ref: '#/components/schemas/ClusterData'
              type: array
            - type: 'null'
          title: Clusters
      type: object
      required:
        - metadata
      title: MapData
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MapMetadata:
      properties:
        dt_update:
          type: string
          title: Dt Update
        ts_update:
          type: integer
          title: Ts Update
        identified_supply:
          $ref: '#/components/schemas/IdentifiedSupply'
      type: object
      required:
        - dt_update
        - ts_update
        - identified_supply
      title: MapMetadata
    NodesData:
      properties:
        top_holders:
          items:
            $ref: '#/components/schemas/AccountAddressWithHolderDataWithMapContext'
          type: array
          title: Top Holders
        magic_nodes:
          anyOf:
            - items:
                $ref: '#/components/schemas/AccountAddressWithDetailsWithMapContext'
              type: array
            - type: 'null'
          title: Magic Nodes
      type: object
      required:
        - top_holders
      title: NodesData
    GroupedTransfer:
      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/GroupedTransferData'
      type: object
      required:
        - from_address
        - to_address
        - data
      title: GroupedTransfer
    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
    IdentifiedSupply:
      properties:
        share_in_cexs:
          type: number
          title: Share In Cexs
        share_in_dexs:
          type: number
          title: Share In Dexs
        share_in_other_contracts:
          type: number
          title: Share In Other Contracts
      type: object
      required:
        - share_in_cexs
        - share_in_dexs
        - share_in_other_contracts
      title: IdentifiedSupply
    AccountAddressWithHolderDataWithMapContext:
      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: AccountAddressWithHolderDataWithMapContext
    AccountAddressWithDetailsWithMapContext:
      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: AccountAddressWithDetailsWithMapContext
    GroupedTransferData:
      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_ref:
          anyOf:
            - $ref: '#/components/schemas/ContractTokenRef'
            - $ref: '#/components/schemas/NativeTokenRef'
          title: Token Ref
      type: object
      required:
        - total_value
        - total_transfers
        - first_date
        - last_date
        - token_ref
      title: GroupedTransferData
    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
    ContractTokenRef:
      properties:
        chain:
          $ref: '#/components/schemas/ChainId'
        address:
          type: string
          title: Address
      type: object
      required:
        - chain
        - address
      title: ContractTokenRef
    NativeTokenRef:
      properties:
        id:
          $ref: '#/components/schemas/NativeTokenId'
      type: object
      required:
        - id
      title: NativeTokenRef
    NativeTokenId:
      type: string
      enum:
        - ETH
        - ETH_BASE
        - SOL
        - TRX
        - BNB
        - APE
        - TON
        - POL
        - AVAX
        - S
        - HYPE
        - MONAD
        - ETH_ARB
        - APT
        - ETH_ROBINHOOD
      title: NativeTokenId
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-ApiKey

````