# Get Address Metadata Source: https://docs.bubblemaps.io/data/api/addresses/metadata GET /v0/addresses/metadata/{address} **Credit cost:** 1 per request. Get metadata and label for a specific address. Labels, tags, and entities come from our refined database of 1B+ identified addresses. Address metadata is only available on custom plans. [Reach out](mailto:api@bubblemaps.io) if you are interested. # Get Batch Addresses Metadata Source: https://docs.bubblemaps.io/data/api/addresses/metadata-batch POST /v0/addresses/metadata **Credit cost:** 1 per address. Get metadata and label for a batch of addresses. Address list is passed in body. Labels, tags, and entities come from our refined database of 1B+ identified addresses. Address metadata is only available on custom plans. [Reach out](mailto:api@bubblemaps.io) if you are interested. # Authentication Source: https://docs.bubblemaps.io/data/api/authentication Get Access to the Bubblemaps API ## Get Your Key To access this API, you'll need an API key. Get one on our [Pro platform](https://pro.bubblemaps.io). ## Credits You get monthly API credits depending on your susbcription. Credit usage resets on your subscription monthly renew date. Monitor and manage your subscription with our [Pro platform](https://pro.bubblemaps.io). If you go above your available credits, you'll start getting 429 errors. Each endpoint consumes a different amount of credit. Some have optional parameters that increase the consumed credit when used. It's all detailed in the documentation of each endpoint. Additionally to this credit system, a 10k calls/minute rate limit is applied at the IP level. ## Using Your Key Pass your key in the `X-ApiKey` header of your requests. Try this out in the [interactive endpoints documentation](/data/api/chains/supported). # Get Supported Chains Source: https://docs.bubblemaps.io/data/api/chains/supported GET /v0/chains **Credit cost:** 0.01 per request. Get the list of chains that we currently support. We've included corresponding ids of the CoinGecko and DEX Screener platforms, which you can use as a common matching reference if needed. # Get Map Data Source: https://docs.bubblemaps.io/data/api/deprecated/get-map-data GET /maps/{chain}/{token_address} Deprecated: use `GET /v0/tokens/map/{chain}/{token_address}` instead. This endpoint will be removed in the future. Deprecated: use `GET /v0/tokens/map/{chain}/{token_address}` instead. This endpoint will be removed in the future. **Credit cost:** 50 per request. 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! 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. 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. # Get Supported Chains Source: https://docs.bubblemaps.io/data/api/deprecated/get-supported-chains GET /chains Deprecated: use `GET /v0/chains` instead. This endpoint will be removed in the future. Deprecated: use `GET /v0/chains` instead. This endpoint will be removed in the future. **Credit cost:** 0.01 per request. Get the list of chains that we currently support. We've included corresponding ids of the CoinGecko and DEX Screener platforms, which you can use as a common matching reference if needed. # Introduction Source: https://docs.bubblemaps.io/data/api/introduction Bubblemaps Data API ## What is this? We've been getting a lot of inquiries from our iFrame partners and other tech teams to expose our data in an API. That's why we're now exploring this option! Keep in mind this is still an early version, that we will build over progressively. Before reading more, make sure you are interested in the Data API, and not the iFrame Integration, which is a different thing entirely. In case of doubt, refer back to the differences [here](/introduction). ## OpenAPI This API follows the OpenAPI standard, the json schema can be found [here](/openapi.json). This can be fed to typing librairies, swagger UIs, AI agents... anything that needs a structured description of the API. # Get Addresses Subgraph Source: https://docs.bubblemaps.io/data/api/relationships/subgraph POST /v0/relationships/subgraph **Credit cost:** 10 per request + 1 per requested address. Get all the transfers between a given list of addresses. By default, only the transfers of [indexed tokens](/data/api/token-model#indexed-tokens) are included. Use the `context_token_key` body parameter to force the inclusion of transfers of a specific token. 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. Relationships between two supernodes (addresses with high volume of transfers) are ignored. Rrelationships between a supernode and a non-supernode are included though. # Token Model Source: https://docs.bubblemaps.io/data/api/token-model How tokens are handled in the Bubblemaps API ## Token Keys Whether it is in endpoints inputs (query parameters, json body, etc) or endpoints outputs (response body), tokens are always referenced by their token key. A token key is the pair of a chain id and a token address: * You can get the list of the available chains in the schema or dynamically with the [Get Supported Chains](/data/api/chains/supported) endpoint. Additional chains **will** be supported in the future, without notice. Make sure that it won't break your typing. * The token address is either the smart contract address of the token, or the constant `"native"` when this is the chain native token, for exemple ETH in the case of the Ethereum blockchain. For EVM chains, both checksum and lowercase addresses are accepted as input, althought the API will always return the lowercase address. Solana addresses are case sensitive. Some examples: ```json theme={null} [ # UNI { "chain": "eth", "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984" }, # BNB { "chain": "bnb", "address": "native" }, # BMT { "chain": "solana", "address": "FQgtfugBdpFN7PZ6NdPrZpVLDBrPGxXesi4gVu3vErhY" } ] ``` ## Indexed Tokens As you surely know, the blockchain is flooded with fake tokens. These are real smart contracts deployed on the blockchain, but they are no legit tokens either because they have never been launched or traded, or even because they are malicious contracts used for dust attacks. That's why we maintain a limited list of 'indexed' tokens. All tokens can be queried in the different endpoints of course, but we only consider the transfers of indexed tokens when computing maps (transfers of non-indexed tokens won't create clusters in maps, that is to avoid false positive clusters). This is sometimes returned as `is_indexed` in tokens info objects. On the map of a given token, transfers of this specific token are always included, even if it is not indexed. (but they won't show up in maps of other tokens) # Get Token Bubble Map Source: https://docs.bubblemaps.io/data/api/tokens/map GET /v0/tokens/map/{chain}/{token_address} **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) | 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). * 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. ### 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. # Get Token Metadata Source: https://docs.bubblemaps.io/data/api/tokens/metadata GET /v0/tokens/metadata/{chain}/{token_address} **Credit cost:** 0.1 per request. Get metadata for a given token. The parameter `return_token_stats` will get you some stats about the token. Costs 0.5 credit per request instead of 0.1. -> link index tokens # Get Batch Tokens Metadata Source: https://docs.bubblemaps.io/data/api/tokens/metadata-batch POST /v0/tokens/metadata **Credit cost:** 0.1 per token. Get metadata for a batch of tokens. Token list is passed as query body. The parameter `return_token_stats` will get you some stats about the tokens. Costs 0.5 credit per token instead of 0.1. -> link index tokens # Search Token Source: https://docs.bubblemaps.io/data/api/tokens/search GET /v0/tokens/search **Credit cost:** 0.5 per request. Search tokens by name, ticker, or address. # Get Token Top Holders Source: https://docs.bubblemaps.io/data/api/tokens/top-holders GET /v0/tokens/holders/{chain}/{token_address} **Credit cost:** 1 per request. Get the top holders of any 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 response 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. * The `return_metadata` query parameter includes the labels and metadata of the holders in the response. * 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 top holders of a token in a specific date in the past, use the `timestamp` parameter (unix timestamp) | Option | Credits | | ---------------------- | ------: | | Base request | 1 | | `limit=250` | +10 | | `limit=500` | +25 | | `return_metadata=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`. # Interactive Demo Source: https://docs.bubblemaps.io/iframe/demo Bubblemaps iFrame Integration Change the chain and token address to update the interactive demo below. Your iFrame integration will follow a similar pattern with chain and token address inputs, see the [quickstart section](/iframe/quickstart) for more details on how to actually integrate the iFrame. # Introduction Source: https://docs.bubblemaps.io/iframe/introduction Bubblemaps iFrame Integration ## What is this? Ready-to-use Bubblemaps. A very easy one-liner integration to feature our visuals into your platform, like an autonomous widget. Our iFrames have been battle-tested by the industry most famous names like CoinGecko and DexScreener. In today's climate of scammy meme-coins, centralized DAOs, celebrities launching rigged tokens with bundled supply, and the ever-growing complexity of blockchain data, you **need** Bubblemaps to navigate the DeFi. Stand out from your competitors: Provide transparency, safety, and easy, visual value to your users with Bubblemaps iFrames. Whether you are a token company, a Dex, or another DeFi entity, you might also be interested in custom labelling on Bubblemaps. We discuss these on a case by case basis, don't hesitate to [reach out](mailto:contact@bubblemaps.io). # Pricing Source: https://docs.bubblemaps.io/iframe/pricing Bubblemaps iFrame Integration ## You need a Partner Id The iFrame will only work if you specify a `partnerId` value. You can use the `demo` partner id to test things out on `localhost` or `0.0.0.0`, but if you want to actually deploy the iFrame on your site, we'll need to set up a real partner id for you. This unique id is what unlocks integration on your domains (we'll ask you your production and development domains to whitelist on our side). We can also set up a custom color theme to better match your brand, it will be triggered by your partner id. ## Basic Usage No worries, if you just want something simple (for example if you’re a token company and want to display your own map on your showcase website) you won't have to pay a subcription. Some one-time fees may apply depending on custom labelling or marketing needs. [Contact us](mailto:contact@bubblemaps.io?subject=Iframe%20Integration%20Inquiry) and we’ll discuss it. ## Exchanges & Analytics Platforms We have multiple subscription plans depending on volume, customization options, chains support, marketing support, etc. Please [get in touch](mailto:contact@bubblemaps.io?subject=Iframe%20Integration%20Inquiry) for more details. # Quickstart Source: https://docs.bubblemaps.io/iframe/quickstart Embed our iFrames in one line of code ## iFrame Tag You can iFrame a bubble map by simply setting the URL of the map in the `src` attribute of an `iframe` html tag, like this: ```html theme={null} ``` Note the simple structure of the URL: ```text theme={null} https://iframe.bubblemaps.io/map?chain=[chain_id]&address=[token_address]&partnerId=[partner_id] ``` `allow="clipboard-write"` is needed for the 'copy' buttons to work on the app (for example to copy the address of a holder). ## Available Chains Currently available chains are `solana`, `eth`, `bsc`, `tron`, `base`, `apechain`, `sonic`, `ton`, `avalanche`, `polygon`, `monad`, and `aptos`. We will keep this list updated. But if you want to get technical and dynamically update your iFrames as we release more chains, you could use our [Supported Chains](/data/api/chains/supported) API endpoint. Don't hesitate to ask. ## Partner Id If you don't have a dedicated partner id yet, you can use `demo` to test things out. More info in the [pricing section](/iframe/pricing). Otherwise, replace `demo` by your actual partner id. It will unlock the integration on your domains. Your partner id is **not** a secret, so you can have it showing in clear in your frontend code. It only unlocks the integration on your domains, and can not be used to impersonate you. ## Styling Of course, you still have to style your iframe in terms of size and border to place it correctly in your layout. Keep in mind that browsers usually apply a default border on iframes, which you'll have to remove. We also recommend using at least a 600px height. ```css theme={null} iframe { width: 100%; height: 700px; border: none; } ``` Exemple with inline styling: ```html theme={null} ``` **Custom color themes** are also available on-demand, no code change needed (the color theme is triggered by the partner id). # Our B2B Products Source: https://docs.bubblemaps.io/introduction Choose between iFrame or API ## Two Separate Products Before getting heads down in the docs, you should take the time to ascertain which of our two products you want to work with. * **iFrame Integration**: Ready-to-use Bubblemaps. Our main product, what most of our clients use. A very easy one-liner integration to feature our visuals into your platform, like an autonomous widget. Battle-tested by the industry most famous names (CoinGecko, DexScreener, etc). * **Data API** *\[Beta]*: Get technical. Directly access our data and present it the way you want within your service. Holders, transfers, clusters, exposed through a REST API. ## Which one should you choose? If you're still unsure what product is the best for you, here's some help: * You are a crypto platform for monitoring tokens, like a chart app, or a telegram monitoring bot, and you want to quickly add some visual value to your app: **Go with the iFrame**. * You are a launchpad, and want to provide an easy visual tool to help your users navigate tokens launched though your platform: **Go with the iFrame**. * You are a token company, and want to demonstrate transparency, validate your tokenomics against your actual supply distribution: **Go with the iFrame** and integrate your own map to your website. * You are a crypto analytics company, like a DeFi analytics app, or a telegram trading bot, and you want to fetch, process, and integrate our data into your codebase and pipelines: **Go with the API**. Whether you are a token company, a Dex, or another DeFi entity, you might also be interested in custom labelling on Bubblemaps. We discuss these on a case by case basis, don't hesitate to [reach out](mailto:contact@bubblemaps.io). You might be interested in both products! We can definitely negociate custom deals for companies with extensive needs. [Reach out](mailto:contact@bubblemaps.io).