Integrate the fan-out widget

Quick start — iframe¶

The simplest path: copy, replace integrator with your wallet, done. The listener auto-sizes the frame as the widget grows.

<iframe id="cherum-widget"
  src="https://app.cherum.io/en/embed?integrator=0xYourWalletAddress&integratorBps=20&theme=dark&accent=%238B6FE6"
  style="width:100%;max-width:460px;height:600px;border:0;border-radius:18px"
  allow="clipboard-write" loading="lazy"></iframe>
<script>
  window.addEventListener('message', function (e) {
    if (e.origin !== 'https://app.cherum.io') return;
    if (e.data && e.data.type === 'cherum-embed:height') {
      document.getElementById('cherum-widget').style.height = e.data.height + 'px';
    }
  });
</script>

Try configurations live in the playground — it generates this snippet for you.

Quick start — script tag¶

One tag, auto-height included. The loader mounts the same secure iframe under the hood and wires the resize listener for you.

<script src="https://cdn.cherum.io/widget.js" async></script>
<div id="cherum-widget"></div>
<script>
  window.addEventListener('load', function () {
    Cherum.mount('#cherum-widget', {
      integrator: '0xYourWalletAddress',  // your wallet — receives your fee
      integratorBps: 20,                  // your cut · default 20 (0.2%) · cap 500
      theme: 'dark',
      accent: '#8B6FE6'                   // any hex — your brand color
    });
  });
</script>

Quick start — React¶

The typed component wraps the same embed. Config maps 1:1 to the script loader.

// npm install @cherum/widget-react
import { CherumWidget } from '@cherum/widget-react';

export default function Pay() {
  return (
    <CherumWidget
      integrator="0xYourWalletAddress"
      integratorBps={20}
      theme="dark"
      accent="#8B6FE6"
      source={{ chain: 'arbitrum', token: 'USDC', amount: '1000' }}
      recipients={[
        { chain: 'base', token: 'USDC' },
        { chain: 'optimism', token: 'USDC' },
      ]}
    />
  );
}

Parameters¶

Same fields in all three forms (URL query for the raw iframe, config object for the loader and React). Everything is optional except integrator — required to earn.

Source & recipients¶

Pre-set destinations are chain × token pairs — the user fills addresses and split percentages inside the widget (they must confirm where their money goes; that stays in their hands).

source: { chain: 'arbitrum', token: 'USDC', amount: '1000' },
recipients: [
  { chain: 'base',     token: 'USDC' },
  { chain: 'optimism', token: 'USDC' },
  { chain: 'polygon',  token: 'USDT' },
]

Payouts widget¶

The same card, switched to mass payouts: your users send one token on one network to a list of address + amount rows — typed in, or pasted as CSV straight from a spreadsheet. Large lists are split into batches automatically — the batch size is whatever fits one transaction on that chain, so it runs from 60 recipients on HyperEVM to 900 on Polygon, and the token path fits more than the native one (546 recipients per transaction for a token on Base) — with pause and resume between batches. Safe multisigs work as senders out of the box: the card detects a contract wallet, queues the batch for co-signers and picks the result up from the chain.

<iframe id="cherum-payouts"
  src="https://app.cherum.io/en/embed?mode=payouts&integrator=0xYourWalletAddress&integratorBps=30&theme=dark"
  style="width:100%;max-width:460px;height:520px;border:0;border-radius:18px"
  allow="clipboard-write" loading="lazy"></iframe>
<script>
  window.addEventListener('message', function (e) {
    if (e.origin !== 'https://app.cherum.io') return;
    if (e.data && e.data.type === 'cherum-embed:height') {
      document.getElementById('cherum-payouts').style.height = e.data.height + 'px';
    }
  });
</script>

Pricing is flat and public — no tiers, no calls, no forms:

• Cherum fee: 0.10% of the batch total. That’s it. A $10,000 payroll batch costs $10 — compare that to per-batch flat fees elsewhere that run into hundreds of dollars.
• Your markup: 100% yours. Set integratorBps up to 300 (3%) — the contract pays it to your wallet in the same transaction as the payout. Verify every settlement in the block explorer; you never have to trust our reports.
• The payer sees both lines before signing: our fee, your fee, and the exact total to pay. No surprises after the fact.
• Use src=base.USDC to pre-select the network and token, lockSource=1 to pin them.

Fees & integrator¶

Two models, two rails — they never blend, and your earnings never come out of Cherum’s fee (or vice versa):

• Through the Cherum contract (Model A): your integratorBps markup is collected by the contract and routed to your integrator wallet on-chain, in the same transaction as the swap. Settled the moment the swap settles — nothing to withdraw.
• Everywhere else (Model B): some swaps run entirely inside a provider, with no Cherum contract in the execution path — every non-EVM source (TON, Solana, Bitcoin, XRP, Cardano…) and direct aggregator swaps on EVM chains. There is no contract to split on, so the provider withholds your markup together with our share and your part accrues off-chain — set your rate in the dashboard (default 0.2%, up to 1%) and withdraw in USDC on Base. One rate, one balance, whatever the route.

Dashboard & payouts¶

• Sign in at dashboard.cherum.io with your integrator wallet — signature only, no email or password.
• Dashboard: your revshare ledger (accrued, pending, paid out, balance), your rate setting, and embed snippets with your wallet baked in.
• Markup paid by the contract is not in the dashboard, by design: it goes to your wallet in the same transaction as the swap, so the block explorer is the receipt — there is nothing for us to report and nothing to trust us on.
• Payouts: request a withdrawal once that balance reaches $50 — paid in USDC on Base to your integrator wallet.

CSP & embedding¶

• The widget runs in an isolated iframe on app.cherum.io — no styles or scripts leak into your page, and your page cannot touch user funds.
• Allow framing: nothing needed on your side — the embed sends frame-ancestors *. Your CSP needs frame-src https://app.cherum.io (and script-src https://cdn.cherum.io if you use the loader).
• Auto-height is one-way: the card posts {type:'cherum-embed:height'} to your page, and the listener in the snippet checks e.origin before resizing. The card itself listens to nothing, so no page it sits on can drive it.
• No trackers, no external fonts — everything is served from Cherum domains.