How to Embed a Token Bubble Map on Your Website

You embed a token bubble map with one iframe and a domain-locked embed key. The Scanner Embed API puts the same interactive map you see on Scanner on your own site, for Solana and Robinhood Chain, with one key for both chains.

This guide covers what the map shows, how to get a key, the exact snippet, the options, domain locking, rate limits, and how to embed explorer views next to it.

What a token bubble map shows

A token bubble map is an interactive graph of who holds a token and how those wallets are connected. Nodes are wallets and tokens. Links are the funding and transfer relationships between them. Color encodes each node's role: the address you searched, its funders, bundled wallets, liquidity, and so on.

A token scan surfaces the top holders with bundle detection, flagging the ones that belong to a coordinated bundle rather than acting independently. That is the part holders and traders care about. A holder list tells you who owns the supply. A bubble map tells you whether twenty holders are really twenty people.

Users can zoom, pan, filter, and open node details right inside your page.

Step 1: Get an embed key

You get an embed key by emailing payments@scanner.net with the domains you will embed on. Embed keys are set up by the team, one per organization, with an allowed-domain list and their own daily and monthly limits. Embed traffic does not draw down a plan's scan allowance. Details are in Plans and access.

Your key starts with emb_ and is 68 characters long.

Step 2: Drop in the iframe

The bubble map embed is a single iframe pointed at the map route with embed=1 and your key. Here is the quick start, as published in the docs:

<iframe
  src="https://www.scanner.net/sol/scanner/TOKEN_MINT/map?embed=1&key=YOUR_API_KEY"
  width="100%"
  height="600"
  sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
  allow="clipboard-write"
  style="border: none; border-radius: 12px;"
></iframe>

Replace TOKEN_MINT with a Solana token mint (or wallet address) and YOUR_API_KEY with your emb_ key.

For Robinhood Chain, swap the path and use a 0x address:

Use www.scanner.net directly. The apex scanner.net redirects to www, which adds a hop inside the iframe.

Keep the sandbox tokens. The map is client-rendered, so it needs allow-scripts. Drop allow-same-origin and the iframe gets an opaque origin, which can get its API calls rejected with 403 EMBED_DOMAIN_REJECTED once your org has allowed domains.

If your site sends a Content-Security-Policy, allow both hosts:

Content-Security-Policy: frame-src 'self' https://www.scanner.net https://scanner.net;

Step 3: Pick a scan mode

The scan mode controls which map you get, and it is optional. Leave it out and the address is auto-detected: a token runs holders, a wallet runs quick.

Append the mode as a bare flag or as mode=:

/sol/scanner/{MINT}/map?embed=1&key={KEY}&traders

Robinhood Chain has no trader maps. Ask for traders there and the embed shows an explanation with a View holders link instead of silently running another scan.

To switch tokens without reloading your page, update the iframe src:

function loadToken(address, chain = "sol") {
  const params = new URLSearchParams({ embed: "1", key: API_KEY });
  document.getElementById("scanner-embed").src =
    `https://www.scanner.net/${chain}/scanner/${encodeURIComponent(address)}/map?${params}`;
}

The implementation guide also has a drop-in React component and a responsive aspect-ratio wrapper.

Step 4: Lock it to your domains

Domain locking decides where your embed key works. Embed keys are publishable: they sit in your page's HTML, so treat them as a public identifier, not a secret.

• No domains configured (public mode). The key works on any site. This is the default for a new org until you ask the team to add domains.
• Domains configured. The iframe response sets a frame-ancestors rule and the browser blocks embedding anywhere else. Direct API calls from other origins get 403 EMBED_DOMAIN_REJECTED.

Registering example.com also covers its subdomains. Registering localhost matches any local port, and localhost:5173 matches only that port.

Validate a key before you mount the iframe. The iframe cannot report an invalid key to your page across origins, so a pre-flight call is the clean way to fail fast:

GET https://api.scanner.net/embeds/validate?key={API_KEY}

{ "valid": true, "domains": ["app.example.com", "staging.example.com"] }

Keys can be rotated. The old key stops working within 5 minutes, because key lookups are cached that long. Full rules are in Authentication.

Step 5: Know the rate limits

Embed rate limits come in three layers, and the third one is the one to plan around.

• IP limit: 7 requests per minute per IP. Returns 429 with RATE_LIMITED.
• Address cooldown: 20 seconds between requests for the same address per org. Returns 429 with EMBED_MINT_COOLDOWN. Cached token maps skip the wait.
• Org usage limits: daily and monthly caps set during onboarding. Returns 429 with EMBED_QUOTA_EXCEEDED.

Scans are cached for 1 hour. A cached result runs no new scan, but every embed request still counts one unit against your daily and monthly limits. Once you are over, requests that need a fresh scan return 429. See Rate limits for the exact errors.

Embedding explorer views

Explorer embeds put a single token, wallet, transaction, or block page on your site with the same emb_ key and domain settings as the map.

Use sol or rh for the chain and append ?embed=1&key={API_KEY}:

<iframe
  title="Solana token explorer"
  src="https://www.scanner.net/embed/sol/token/So11111111111111111111111111111111111111112?embed=1&key=YOUR_API_KEY"
  width="100%"
  height="720"
  sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
  allow="clipboard-write"
  style="border: none; border-radius: 12px;"
></iframe>

Links, tabs, filters, and pagination stay inside the iframe and keep the key. Loading or paging an explorer view does not start a deep scan or spend map-scan credits. More in Explorer views.

Embed API vs Scanner API vs Indexer API

Scanner has three APIs, and the right one depends on where your code runs.

If you want a bubble map on a page, use the Embed API. If your backend needs bundle data or explorer lookups, use the Scanner API with a sk_live_ key. Secret keys are rejected when called from a browser, and embed keys are for browsers only. If you are indexing Robinhood Chain into your own system, use the Indexer.

Start embedding

Email payments@scanner.net with your domains, paste the iframe, and your users get a live bubble map with bundle detection without leaving your site.

Read the Embed overview for every parameter, and the API overview to compare all three APIs.