Buy Widget

The Hizz Buy Widget drops the buy/sell box onto any site. It renders in an isolated iframe served from https://www.hizz.io/embed/buy, so partner pages never load the full Hizz app or its styles — they just get the trade box.

Loader script: https://www.hizz.io/widget/hizz-buy.js
Frame URL: https://www.hizz.io/embed/buy?asset=<policyId|assetId>
Version: window.HizzBuyWidget.version (1.2.0) · no API key required

The loader auto-detects its own origin from the <script src>, so the iframe always points back to wherever the script was loaded from. Use https://www.hizz.io unless you self-host.

Live demo

The real widget, embedded cross-origin. This example uses SNEK; swap in any Cardano asset.

This preview loads https://www.hizz.io/widget/hizz-buy.js and mounts with window.HizzBuyWidget.mount(...), the same path as a partner site using the loader. Wallets that only inject into the top-level page, including VESPR, can be bridged into the frame when window.cardano.vespr exists on this page.

Live — SNEK / ADA, dark theme

Quick start

The fastest integration — drop one tag where the widget should appear. When the script itself carries data-asset, the loader inserts a host element right after it and mounts. Nothing else required.

<script
  src="https://www.hizz.io/widget/hizz-buy.js"
  data-asset="279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b"
  data-theme="dark"
  async
></script>

Integration methods

1. Container element (recommended)

Full control over placement. The loader scans for [data-hizz-buy-widget] on load and mounts each match.

<div
  data-hizz-buy-widget
  data-asset="279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b"
  data-theme="light"
></div>

<script src="https://www.hizz.io/widget/hizz-buy.js" async></script>

2. Custom element

<hizz-buy-widget
  asset="279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b"
  theme="snek"
></hizz-buy-widget>

<script src="https://www.hizz.io/widget/hizz-buy.js" async></script>

3. Programmatic mount

For containers that appear after load (modals, SPA routes, infinite scroll). mount(target, options) takes a CSS selector or an element, returns the iframe, and is idempotent per element.

<div id="hizz-buy"></div>
<script src="https://www.hizz.io/widget/hizz-buy.js"></script>
<script>
  window.HizzBuyWidget.mount("#hizz-buy", {
    asset: "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b",
    theme: "dark",
    partner: "hodlcomp",
    ref: "august-launch",
    height: 640,
    onTradeSubmitted(trade) {
      console.log(`${trade.volumeAda} ADA submitted`, trade.txHash);
    },
  });
</script>

window.HizzBuyWidget is created when the loader runs. If you load it with async or defer, its order relative to an inline mount() call is not guaranteed — use the blocking order above or attach mount() to the loader script’s load event.

4. Raw iframe (fallback only)

For strict CSP or static-only pages. This can render the trade box, but it should not be the primary integration when wallet connect matters. You lose automatic height resizing — pick a fixed height that fits — and the wallet bridge: wallets that only inject into the top-level page (e.g. VESPR) will not be connectable inside the frame.

If you need VESPR or mobile in-app browser support, do not ship a standalone raw iframe. Use methods 1-3, or add the loader script below so it can adopt the iframe and bridge top-level wallets into the widget.

Already shipped a raw iframe? Just add the loader script tag anywhere on the same page — it adopts existing /embed/buy iframes automatically, enabling auto-resize and the wallet bridge with no markup changes:

<script src="https://www.hizz.io/widget/hizz-buy.js" async></script>

<iframe
  src="https://www.hizz.io/embed/buy?asset=279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b&theme=dark"
  title="Hizz buy widget"
  loading="lazy"
  allow="clipboard-write; web-share"
  referrerpolicy="strict-origin-when-cross-origin"
  style="width:100%;max-width:420px;height:620px;border:0;border-radius:18px;background:transparent;"
></iframe>

Options

Pass options as kebab-case data-* attributes on the host element/script, as attributes on the custom element, or as camelCase keys in mount(target, options).

Option	Aliases	Default	Notes
`asset`	`token`, `token-id`, `policy-id`	— (required)	Cardano policy ID (56 hex chars) or full asset ID (policy + hex-encoded name). A bare policy ID resolves to its primary asset automatically.
`theme`	—	`dark`	`dark` · `light` · `snek` · `transparent`.
`partner`	—	—	Reporting key stored with each submitted trade order and returned in trade events. Lowercase letters, numbers, `.`, `_`, `:`, and `-`; max 64 characters.
`ref`	—	—	Optional partner campaign/reference key stored with the order and returned as `ref`; max 128 characters.
`width`	—	`100%`	CSS width of the iframe. Loader only.
`height`	—	`620`	Initial height (px) before auto-resize. Loader only.
`radius`	—	`18px`	iframe `border-radius`. Loader only.
`title`	—	`Hizz buy widget`	iframe `title` (accessibility). Loader only.

Themes

dark — default Hizz dark surface with a soft brand glow.
light — light surface.
snek — Snek “spotlight” mint-on-charcoal theme (good for snek.fun tokens).
transparent — no page background, border, or padding. Use this to sit the box flush inside your own card or section.

Partner attribution and trade volume

Set a stable partner value on every widget placement whose volume you want attributed. For example, all HODLCOMP placements should use partner: "hodlcomp" (or data-partner="hodlcomp"). Hizz stores that value on the corresponding trade order as soon as the swap is built. ref can split a partner’s traffic into campaigns without creating a second partner identity. partner is an attribution label, not an API secret, payout instruction, or server webhook. Hizz can aggregate finalized volume from its verified trade orders later; the browser event below provides immediate per-trade data to the partner page.

Programmatic callback

onTradeSubmitted runs after the connected wallet returns an on-chain transaction hash:

<div id="hizz-buy"></div>
<script src="https://www.hizz.io/widget/hizz-buy.js"></script>
<script>
  window.HizzBuyWidget.mount("#hizz-buy", {
    asset: "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b",
    partner: "hodlcomp",
    ref: "homepage",
    onTradeSubmitted(trade) {
      // Exact decimal strings: safe to store or sum without float rounding.
      console.log(trade.txHash);
      console.log(trade.volumeLovelace); // e.g. "5000000"
      console.log(trade.volumeAda);      // e.g. "5"
    },
  });
</script>

The callback reports one submitted market swap, not the partner’s historical cumulative total. Sum volumeLovelace for immediate page analytics; use Hizz’s verified reporting for final totals. A limit-order placement is not trading volume and does not emit this event. For buys, volume is the ADA input. For sells/recoveries, it is the quoted ADA output (volumeBasis: "expected_output", with minimum output as a fallback). The callback is a submission notification, not confirmation that the chain has included the transaction.

{
  source: "hizz",
  type: "hizz:buy-widget:trade-submitted",
  version: 1,
  status: "submitted",
  partner: "hodlcomp",
  ref: "homepage",
  txHash: "<64-character transaction hash>",
  orderId: "<Hizz order id or null>",
  side: "buy",
  tokenAssetId: "<policy id + asset name>",
  tokenTicker: "SNEK",
  tokenIn: "lovelace",
  tokenOut: "<policy id + asset name>",
  amountInBase: "5000000",
  expectedAmountOutBase: "...",
  minAmountOutBase: "...",
  volumeLovelace: "5000000",
  volumeAda: "5",
  volumeBasis: "input",
  provider: "dexhunter",
  routeProtocol: "...",
  submittedAt: "2026-08-18T12:00:00.000Z"
}

Raw `postMessage`

The iframe also posts the same payload to its parent. This supports raw iframe integrations and event-bus style integrations without a mount callback:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://www.hizz.io") return;
  const trade = event.data || {};
  if (
    trade.source === "hizz" &&
    trade.type === "hizz:buy-widget:trade-submitted"
  ) {
    console.log(`${trade.volumeAda} ADA`, trade.txHash);
  }
});

Always verify event.origin. The loader does this origin and iframe-source validation before it invokes onTradeSubmitted.

Auto-resize

The framed page measures its content and posts its height to the parent:

{ source: "hizz", type: "hizz:buy-widget:resize", height: <px> }

The loader listens for this and adjusts the matching iframe (floor 360px), so the box grows and shrinks as users switch between buy / sell / recover. If you embed a raw iframe (method 4) you can subscribe to the same message:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://www.hizz.io") return;
  const data = event.data || {};
  if (data.source === "hizz" && data.type === "hizz:buy-widget:resize") {
    iframe.style.height = Math.max(360, Number(data.height)) + "px";
  }
});

The embedded box uses the same trade engine as hizz.io, but it runs in a cross-origin iframe on your page, which limits how users can authenticate. CIP-30 wallets are the only sign-in path inside an embed (social login is hidden there). Two ways a wallet becomes available in the frame:

Direct injection — most extensions (Eternl, Lace, …) inject window.cardano into every frame, so the widget sees them natively.
Wallet bridge (loader v1.1.0+) — some wallets, VESPR in particular, only inject into the top-level page. The loader script running on your page detects them and proxies the CIP-30 calls into the frame over postMessage. This is automatic — no partner code, no config. Approval and signing prompts are still rendered by the wallet itself. Loader 1.1.1+ also keeps watching for widgets/iframes inserted after page load and re-checks the parent page’s wallets while the connect dialog is open, which helps mobile in-app browsers whose providers inject late.

Hizz managed wallet & social login (email, Google, Telegram) rely on first-party hizz.io cookies and OAuth redirects, both blocked in cross-origin iframes and under third-party-cookie restrictions in Safari, Brave, and Chrome. Full account login is not available inside a cross-origin embed — the widget hides those options and offers wallet connect only. Link out to the token page on hizz.io for the full account experience.

Requirements

HTTPS only — clipboard, Web Share, and secure cookies need a secure context on both pages.
One widget per container. Mounting is idempotent per element.
The /embed/* page sets no X-Frame-Options, so it embeds from any origin.
The loader script is edge-cached for 5 minutes; frame content is always fresh.

Troubleshooting

Symptom	Likely cause
”Widget unavailable — Missing or invalid Cardano asset id”	`asset` is empty or not valid hex ≥ 56 chars. Pass a policy ID or asset ID.
”Token not found”	The policy ID has no resolvable asset on the supported DEXes.
Blank box / nothing mounts	Loader ran before the container existed — use programmatic `mount()` or move the `<script>` after the container.
Height never adjusts	Raw iframe without subscribing to the resize message (see Auto-resize).
Stuck on “connect wallet”	Cross-origin embed; extension wallet not injecting, or account login attempted (unsupported in-frame).
VESPR missing from the wallet list	The page is a standalone raw iframe (no loader → no wallet bridge), the top-level page does not expose `window.cardano.vespr`, or the loader is cached older than `1.2.0`. Fix by adding `https://www.hizz.io/widget/hizz-buy.js` or switching to methods 1-3; the script cache refreshes within 5 minutes.
`onTradeSubmitted` never runs	Use programmatic `mount()` and pass a function, or listen for the raw `postMessage`. Data attributes cannot contain callbacks. Confirm the loader has refreshed to `1.2.0`.

Get started

Features

AI Trading

Developers

Learn more

Live demo

Quick start

Integration methods

1. Container element (recommended)

2. Custom element

3. Programmatic mount

4. Raw iframe (fallback only)

Options

Themes

Partner attribution and trade volume

Programmatic callback

Raw `postMessage`

Auto-resize

Requirements

Troubleshooting

​Live demo

​Quick start

​Integration methods

​1. Container element (recommended)

​2. Custom element

​3. Programmatic mount

​4. Raw iframe (fallback only)

​Options

​Themes

​Partner attribution and trade volume

​Programmatic callback

​Raw postMessage

​Auto-resize

​Trading & sign-in inside the embed

​Requirements

​Troubleshooting

Live demo

Quick start

Integration methods

1. Container element (recommended)

2. Custom element

3. Programmatic mount

4. Raw iframe (fallback only)

Options

Themes

Partner attribution and trade volume

Programmatic callback

Raw `postMessage`

Auto-resize

Trading & sign-in inside the embed

Requirements

Troubleshooting