Skip to content

Instantly share code, notes, and snippets.

Last active October 7, 2023 21:29
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save joel-moonlight/070e7f406e2ba7a8f2b1609de835a1c4 to your computer and use it in GitHub Desktop.
Save joel-moonlight/070e7f406e2ba7a8f2b1609de835a1c4 to your computer and use it in GitHub Desktop.

Bubblemaps Iframes


Basic Usage

No worries, if you just want something simple (for example if you’re a token and want to display your map on your showcase website) it’ll most likely be free. Contact us and we’ll discuss it, we might even want to share your initiative on our socials.

Exchanges & Analytics Platforms

We have multiple pricings depending on how many bubble maps need to be computed on your platform (index rate & refresh rate). Please, get in touch for more details.

Basic Integration

You can iframe a bubble map by simply specifying the url of the map in the src attribute, like this:

<iframe src="" />

The app automatically detects that it is displayed in a iframe and automatically handles the hiding of unwanted components like the navbar.

Note the simple structure of the url:[chain]/token/[contract_address]. For now, available chains are eth, bsc, ftm, avax, cro, arbi and poly.

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, so if you don’t want it you’ll have to specify border:none; on your styling.

Please also note that only the graph view is available for iframing, other pages like the homepage or the listed token page will display errors if you try to iframe them.


Bubblemaps non-premium restrictions apply in the same way they do on the main website. Which means that to be fully functionnal, the iframe has to reference a publicly available bubble map. This includes all the tokens listed on Bubblemaps, and specific tokens or NFT collections that we specifically made public. Get in touch with our team to make the tokens listed on your platform publicly accessible.

To make things easier on your side, we’ve created an endpoint that you can call before rendering an iframe for a token or NFT collection to check if its bubble map is publicly available AND ready to display (ie already computed, in order to avoid any waiting or potential errors on the iframe). The endpoint guarantees that the map will be displayed fast and without restriction. We highly advice you to use it to conditionally render bubble maps iframes on your app.

It is called with a chain and a token parameter, just like the iframe:

It will always return a status field that can be OK or KO.

  • If it's OK, another field availability will be there with a boolean value. A true value indicates that the corresponding iframe is ready to be displayed.
{"status":"OK", "availability":true}
  • If it's KO, a field message will be available, with an explanatory value like Invalid chain parameter for example.
{"status":"KO", "message":"Invalid token parameter"}

Useful Options


We made theming available on iframes so that Bubblemaps can be integrated smoothly in your interface.

For that, please ask our team to prepare a custom color palette. Then, your theme will simply be available by adding the corresponding theme query parameter to the iframe src attribute.

The theme is loaded dynamically, which means that if color changes are needed, they can be performed by our team without any code change on your side.

However, this also means that the standard Bubblemaps dark background will be showing while the theme is loading at the very beginning of the iframe render, resulting in a quick "flash". To avoid that, you can specify a second query parameter loading_color to define a color to display while the theme is loading. Basically, using the same color as the background will make the whole process seamless to the eyes of the user.

In the end, it should look like this:

<iframe src="" />

Scroll Behaviour

By default, scrolling on a bubble map allow to zoom or dezoom the visualisation. In the case of an iframe integration, this means that the scroll behaviour is 'hijacked' by the iframe when the user is hovering it.

Depending on your layout, it could disrupt the user experience on your site. So if you want to, you can disable this behaviour with the prevent_scroll_zoom query parameter. No worries, the users will still be able to handle the zoom of the visualisation by double-clicking on it or by using the zoom buttons at the bottom right.

<iframe src="" />

Layout Tweaks

Depending on your overall layout, the space you saved for the Bubblemaps iframe might be small, thus making the Bubblemaps elements like the top buttons or the wallets table feel a bit 'squeezed'. Some options are available to make up for this:

  • small_text: Will make the texts, buttons, and a variety of other elements a little smaller. This will help to get some feeling of space.
  • hide_context: Will remove the name of the token and the scanner link from the top buttons. This will lighten the iframe, while this information is most likely already available on the page you integrated the iframe into.
<iframe src="" />
Copy link

artanagh commented Oct 7, 2023


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment