> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget [IFrame]

The CabalSpy widget renders a live bubble map of wallet activity for a single address. You embed it with one `<iframe>`; everything else (data, styling, live updates) is handled by CabalSpy. It supports Solana, Base, BNB and Robinhood.

## Quickstart

Drop this into your page and replace the address:

```html theme={null}
<iframe
  src="https://widget.cabalspy.xyz/widget?address=YOUR_WALLET_ADDRESS&chain=SOL"
  width="100%"
  height="600"
  style="border:0;border-radius:16px;overflow:hidden"
  loading="lazy"
  referrerpolicy="strict-origin-when-cross-origin"
  title="CabalSpy Wallet Widget">
</iframe>
```

That is the whole integration. The widget reads its configuration from the URL query string, connects to CabalSpy for live data, and updates itself.

<Note>
  Before it renders on your domain, your domain has to be whitelisted (see [Domain allow-list](#domain-allow-list)). Send us the domain(s) you will embed on.
</Note>

## Parameters

The widget is configured entirely through query parameters on the `/widget` URL.

<ParamField query="address" type="string" required>
  The wallet address to display. A Solana base58 address, or an EVM `0x…` address for Base, BNB and Robinhood.
</ParamField>

<ParamField query="chain" type="string">
  Which chain the address belongs to. One of `SOL`, `BASE`, `BNB`, `RH` (Robinhood). We strongly recommend always setting this explicitly — see [Choosing the chain](#choosing-the-chain).
</ParamField>

## Choosing the chain

Solana and EVM addresses look different (base58 vs `0x…`), but Base, BNB and Robinhood all use `0x…` addresses and cannot be told apart from the address alone. **Always pass `chain` explicitly** so the widget shows the right data:

| Chain     | `chain` value | Address format | Rings shown       | Value unit |
| --------- | ------------- | -------------- | ----------------- | ---------- |
| Solana    | `SOL`         | base58         | KOL, Smart, Whale | SOL        |
| Base      | `BASE`        | `0x…`          | KOL, Smart        | ETH        |
| BNB       | `BNB`         | `0x…`          | KOL, Smart        | BNB        |
| Robinhood | `RH`          | `0x…`          | KOL, Smart        | ETH        |

```html Robinhood example theme={null}
<iframe
  src="https://widget.cabalspy.xyz/widget?address=0xYourWalletAddress&chain=RH"
  width="100%" height="600"
  style="border:0;border-radius:16px" loading="lazy"
  title="CabalSpy Wallet Widget"></iframe>
```

<Note>
  Robinhood uses the chain id `RH`. Values are denominated in ETH, and — like Base and BNB — the widget shows KOL and Smart Money rings (no marketcap-only features, which exist for Solana only).
</Note>

## Sizing and responsiveness

The widget fills the iframe, so size the iframe, not the widget. Use a fluid width and a fixed or aspect-ratio height.

```html Responsive wrapper theme={null}
<div style="position:relative;width:100%;max-width:520px;aspect-ratio:1/1.15;margin:auto">
  <iframe
    src="https://widget.cabalspy.xyz/widget?address=YOUR_WALLET_ADDRESS&chain=SOL"
    style="position:absolute;inset:0;width:100%;height:100%;border:0;border-radius:16px"
    loading="lazy" title="CabalSpy Wallet Widget"></iframe>
</div>
```

A square-ish area (roughly 1:1 to 1:1.2) works best for the bubble layout. On mobile give it at least \~360 px of height.

## Domain allow-list

For security the widget only renders inside pages on approved domains. Send us the hostname(s) you will embed on (for example `app.yoursite.com`) and we add them to the allow-list. All subdomains of an approved domain are covered automatically.

Until your domain is approved the iframe will return `403` for its data calls. A direct visit to the widget URL in a browser tab always works, which is handy for testing.

## Live updates

Once loaded, the widget keeps itself current over a WebSocket — new buys and sells animate in without a reload. There is nothing to configure for this; it uses the same connection CabalSpy manages for you.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The widget is blank / shows 403">
    Your embedding domain is not on the allow-list yet, or the address has no tracked wallets. Confirm the domain was approved and that `address` is correct for the given `chain`.
  </Accordion>

  <Accordion title="Wrong data for a 0x address">
    Base, BNB and Robinhood share the `0x…` format. Set `chain` explicitly (`BASE`, `BNB` or `RH`) instead of relying on auto-detection.
  </Accordion>

  <Accordion title="Robinhood shows nothing">
    Robinhood (`chain=RH`) requires the Robinhood-enabled widget build to be live. If RH data is not appearing, the update may not be deployed yet on your instance.
  </Accordion>
</AccordionGroup>