Build on flipper

Overview

flipper is a coin flip on majors, Robinhood stock tokens and a curated set of Robinhood Chain tokens, against a house bankroll held in $FLIPPER. At launch a flip has a 45% win chance and pays 2× in the token you staked (2.05× on $FLIPPER flips), improving to 47.5% at 2× as the protocol grows. Each flip settles in one transaction. The main docs page explains the odds, randomness and settlement.

Your partner id

Give your integration a partner id (letters, digits and . _ : -, up to 64 characters). The widget, embed and SDK API client echo it in every event payload and send it as the X-Flipper-Partner header on flipper API calls, so activity through your integration is attributed to you. It isn't a secret. acme in the samples is a placeholder.

Partners (ERC-8021)

A registered partner code also attributes your players' flips onchain. The widget and SDK add it to each flip as an ERC-8021 data suffix, and the house credits you on every attributed flip.

• Your cut. Each code sits in a tier that earns 10%, 20% or 30% of the flip's expected edge. Keep it as revenue, give it to players as better odds, or set a split.
• How it's paid. Your share accrues onchain on losing flips (the only ones that pay the house), sized to match your cut on average. Anyone can pay it out to your payout address with claimPartner(id).
• Registration needs approval. A code is 1–32 characters of a-z 0-9 _ -. Register it with a payout address and the share you give back as odds, then ask the flipper team to approve it into a tier.
• Same attribute everywhere. Set partner to your code on the widget, embed or SDK client. An id that isn't an approved code still works for reporting, at normal odds.

import { createFlipperClient } from "@flipperdotfamily/sdk";

// your approved partner code: flips from this client carry it onchain (an ERC-8021 suffix)
const flipper = createFlipperClient({ publicClient, walletClient, addresses, partner: "your-code" });

const pv = await flipper.preview(token, amount); // the odds your players get, discount included
await flipper.flip({ token, amount });           // attributed to you onchain

// your share accrues on losing flips; anyone can pay it out to your payout address
const id = await flipper.partnerIdOfCode("your-code");
const { amount: paid } = await flipper.claimPartner(id);

Choose your path

Quickstart

Each snippet renders the widget and wires a wallet. Without a wallet the widget runs read-only (live prices, odds and the token list) and its button reads “Connect wallet”.

<script src="https://cdn.jsdelivr.net/npm/@flipperdotfamily/widget@0/dist/cdn/flipper-widget.js"></script>

<flipper-widget theme="dark" partner="acme"></flipper-widget>

<script>
  const flipper = document.querySelector("flipper-widget");
  flipper.provider = window.ethereum; // any EIP-1193 provider; leave it unset for read-only

  // the user pressed Connect (or Flip) while disconnected: open your wallet UI
  flipper.addEventListener("connect-request", (e) => {
    e.preventDefault(); // you handle it
    window.ethereum
      ?.request({ method: "eth_requestAccounts" })
      .then(() => flipper.refresh()); // re-read accounts, chain and balances
  });

  flipper.addEventListener("flip-settled", (e) => {
    // "won" | "lost" | "refunded", and the payout in wei
    console.log(e.detail.outcome, e.detail.payout);
  });
</script>

<script type="module">
  import "https://cdn.jsdelivr.net/npm/@flipperdotfamily/widget@0/dist/cdn/flipper-widget.esm.js";
</script>

npm i @flipperdotfamily/widget   # lit, viem and @flipperdotfamily/sdk come along as dependencies

import { onFlipperEvent } from "@flipperdotfamily/widget"; // also registers <flipper-widget> (a no-op on the server)

const flipper = document.createElement("flipper-widget"); // typed as FlipperWidget
flipper.provider = window.ethereum;
flipper.partner = "acme";
flipper.theme = { mode: "dark", accent: "#ff5a1f", radius: 16 };
document.querySelector("#flip")!.append(flipper);

// typed listeners (the detail comes first); each returns an unsubscribe function
const off = onFlipperEvent(flipper, "flip-settled", (d) => console.log(d.outcome, d.payout));
onFlipperEvent(flipper, "error", (d) => console.warn(d.code, d.message));

npm i @flipperdotfamily/react

"use client";
import { FlipperWidget } from "@flipperdotfamily/react";
import { useConnect, useWalletClient } from "wagmi";
import { injected } from "wagmi/connectors";

export function Flip() {
  const { data: walletClient } = useWalletClient(); // undefined until connected
  const { connect } = useConnect();

  return (
    <FlipperWidget
      walletClient={walletClient}
      theme="dark"
      partner="acme"
      onConnectRequest={() => connect({ connector: injected() })}
      onFlipSettled={(d) => console.log(d.outcome, d.payout)}
    />
  );
}

import { FlipperConfigProvider } from "@flipperdotfamily/react";

// defaults for every <FlipperWidget> below it
<FlipperConfigProvider
  config={{ partner: "acme", theme: { mode: "dark", accent: "#ff5a1f" } }}
>
  <App />
</FlipperConfigProvider>

import { useRef } from "react";
import { FlipperWidget, type FlipperWidgetElement } from "@flipperdotfamily/react";

const ref = useRef<FlipperWidgetElement>(null);
<FlipperWidget ref={ref} variant="button" buttonLabel="Flip it" />;
ref.current?.open();    // button variant: open the modal (and close())
ref.current?.refresh(); // re-read accounts, chain and balances, e.g. right after you connect

// app/flip/flip-widget.tsx
"use client";
import { FlipperWidget } from "@flipperdotfamily/react";
import { useConnectModal } from "@rainbow-me/rainbowkit";
import { useWalletClient } from "wagmi";

export function FlipWidget() {
  const { data: walletClient } = useWalletClient();
  const { openConnectModal } = useConnectModal();
  return (
    <FlipperWidget
      walletClient={walletClient}
      partner="acme"
      theme="auto"
      onConnectRequest={() => openConnectModal?.()}
      style={{ minHeight: 560 }} // reserve the card's height: no layout shift
    />
  );
}

// app/flip/page.tsx (a server component)
import { FlipWidget } from "./flip-widget";

export default function Page() {
  return <FlipWidget />;
}

npm i @flipperdotfamily/vue

<script setup lang="ts">
import { FlipperWidget } from "@flipperdotfamily/vue";

const provider = window.ethereum; // or your wallet kit's EIP-1193 provider
const open = () => provider?.request({ method: "eth_requestAccounts" });
const onSettled = (d: { outcome: string; payout: string }) =>
  console.log(d.outcome, d.payout);
</script>

<template>
  <FlipperWidget
    :provider="provider"
    theme="dark"
    partner="acme"
    @connect-request="open"
    @flip-settled="onSettled"
  />
</template>

// main.ts: register <FlipperWidget> globally, with defaults
import { createApp } from "vue";
import { FlipperPlugin } from "@flipperdotfamily/vue";
import App from "./App.vue";

createApp(App).use(FlipperPlugin, { partner: "acme", theme: "dark" }).mount("#app");

npm i @flipperdotfamily/svelte

<script lang="ts">
  import { FlipperWidget } from "@flipperdotfamily/svelte";

  const provider = window.ethereum; // or your wallet kit's EIP-1193 provider
  let element = $state<HTMLElement>(); // the <flipper-widget> itself
  const open = () => provider?.request({ method: "eth_requestAccounts" });
</script>

<FlipperWidget
  {provider}
  theme="dark"
  partner="acme"
  onConnectRequest={open}
  onFlipSettled={(d) => console.log(d.outcome, d.payout)}
  bind:element
/>

npm i @flipperdotfamily/angular

import { Component, ViewChild } from "@angular/core";
import { FlipperWidgetComponent } from "@flipperdotfamily/angular";
import type { FlipperEventMap } from "@flipperdotfamily/widget";

@Component({
  selector: "app-flip",
  standalone: true,
  imports: [FlipperWidgetComponent], // no CUSTOM_ELEMENTS_SCHEMA needed
  template: `
    <flipper-widget
      [provider]="provider"
      theme="dark"
      partner="acme"
      (connectRequest)="open()"
      (flipSettled)="onSettled($event)"
    ></flipper-widget>
  `,
})
export class FlipComponent {
  provider = (window as any).ethereum; // or your wallet kit's EIP-1193 provider
  @ViewChild(FlipperWidgetComponent) flipper?: FlipperWidgetComponent;

  open() {
    this.provider?.request({ method: "eth_requestAccounts" });
  }
  onSettled(d: FlipperEventMap["flip-settled"]) {
    console.log(d.outcome, d.payout);
  }
}

import "@flipperdotfamily/widget";

<flipper-widget
  prop:provider={provider()}
  attr:theme="dark"
  attr:partner="acme"
  on:flip-settled={(e) => console.log(e.detail.outcome)}
/>;

// once, in a .d.ts: let Solid's JSX know the tag
declare module "solid-js" {
  namespace JSX {
    interface IntrinsicElements {
      "flipper-widget": HTMLAttributes<HTMLElement> & {
        [k: `${"prop" | "attr" | "on"}:${string}`]: unknown;
      };
    }
  }
}

import "@flipperdotfamily/widget"; // first, so Preact sees the element's properties

<flipper-widget
  provider={provider}
  theme="dark"
  partner="acme"
  onflip-settled={(e) => console.log(e.detail.outcome)}
/>;

Wallet wiring

The host owns the wallet. The widget has no wallet modal and never holds keys. It reads the chain through its own RPC and uses your wallet only to send transactions the user confirms. Give it one of:

On the wrong chain the button reads “Switch to Robinhood Chain” and sends wallet_switchEthereumChain, adding the chain with wallet_addEthereumChain when the wallet answers 4902.

"use client";
import { FlipperWidget } from "@flipperdotfamily/react";
import { useWalletClient } from "wagmi";

export function Flip({ openConnect }: { openConnect: () => void }) {
  // wagmi hands you a new client when the account or chain changes
  const { data: walletClient } = useWalletClient();
  return <FlipperWidget walletClient={walletClient} onConnectRequest={openConnect} />;
}

"use client";
import { useEffect, useState } from "react";
import { FlipperWidget } from "@flipperdotfamily/react";
import { useAccount } from "wagmi";

export function Flip({ openConnect }: { openConnect: () => void }) {
  const { connector, isConnected } = useAccount();
  const [provider, setProvider] = useState<unknown>(null);

  useEffect(() => {
    if (!isConnected || !connector) return setProvider(null);
    let live = true;
    // the connector's EIP-1193 provider
    void connector.getProvider().then((p) => live && setProvider(p));
    return () => {
      live = false;
    };
  }, [connector, isConnected]);

  return <FlipperWidget provider={provider} onConnectRequest={openConnect} />;
}

import "@flipperdotfamily/widget";
import { createWalletClient, custom } from "viem";

const flipper = document.querySelector("flipper-widget")!;

// simplest: the EIP-1193 provider. The widget follows accountsChanged / chainChanged itself
flipper.provider = window.ethereum;

// or a viem WalletClient (build a new one when the account changes)
const [account] = await window.ethereum.request({ method: "eth_requestAccounts" });
flipper.walletClient = createWalletClient({ account, transport: custom(window.ethereum) });

import "@flipperdotfamily/widget";
import { BrowserProvider } from "ethers";

const eip1193 = window.ethereum;              // the object you hand to BrowserProvider
const ethersProvider = new BrowserProvider(eip1193); // your app keeps using ethers as before

const flipper = document.querySelector("flipper-widget")!;
flipper.provider = eip1193; // NOT ethersProvider: the widget speaks EIP-1193
flipper.addEventListener("connect-request", (e) => {
  e.preventDefault();
  void ethersProvider.send("eth_requestAccounts", []);
});

"use client";
import { FlipperWidget } from "@flipperdotfamily/react";
import { useAppKit, useAppKitProvider } from "@reown/appkit/react";

export function Flip() {
  const { open } = useAppKit();
  // EIP-1193; undefined while disconnected
  const { walletProvider } = useAppKitProvider("eip155");

  return <FlipperWidget provider={walletProvider} onConnectRequest={() => open()} />;
}

"use client";
import { FlipperWidget } from "@flipperdotfamily/react";
import { useConnectModal } from "@rainbow-me/rainbowkit";
import { useWalletClient } from "wagmi";

export function Flip() {
  const { data: walletClient } = useWalletClient(); // RainbowKit is wagmi underneath
  const { openConnectModal } = useConnectModal();

  return (
    <FlipperWidget walletClient={walletClient} onConnectRequest={() => openConnectModal?.()} />
  );
}

Iframe embed

The hosted embed at https://flipper.family/embed is the same <flipper-widget> on a full-bleed page with no wallet of its own. Use it to keep the widget's code out of your page (a strict CSP, framework isolation, a site builder). It borrows your wallet over a postMessage bridge and reports its events and height back to you.

URL parameters

Every parameter is optional.

https://flipper.family/embed?chain=4663&theme=dark&accent=4cc2ff&partner=acme

mountFlipperIframe

@flipperdotfamily/widget/host creates the iframe and runs the host side of the bridge. It pins hostOrigin to your origin, checks every message's source and origin, forwards wallet requests to your provider (refusing methods outside the bridge's list with 4200), pushes account and chain changes, and sizes the iframe from the widget's resize events.

import { mountFlipperIframe } from "@flipperdotfamily/widget/host";

const embed = mountFlipperIframe({
  container: "#flipper", // element or selector
  // any EIP-1193 provider; null = read-only until setProvider()
  provider: window.ethereum,
  // the URL params below
  params: { theme: "dark", accent: "#ff5a1f", partner: "acme" },
  // anything else in FlipperEmbedConfig, sent as ?config=
  config: { brandName: "Acme", tagline: "Double or nothing on Acme" },
  // default: provider.request({ method: "eth_requestAccounts" })
  onConnectRequest: () => openMyWalletModal(),
  onEvent: (name, data) => console.log(name, data), // every widget event
});

// later
embed.setProvider(nextProvider);     // after your user connects or switches wallets
embed.setConfig({ theme: "light" }); // live config
embed.destroy();

For a fixed-size frame (a sidebar, dashboard tile or full-screen panel), pass fit: "fill". The iframe fills its container, which needs a height, and the widget lays out inside it from about 240×360 up.

mountFlipperIframe({ container: "#tile", provider, fit: "fill", params: { mode: "single", token: "0x…your token" } });
// #tile { width: 360px; height: 480px }

Without a bundler, load https://flipper.family/embed/flipper-host.js (also on jsDelivr as https://cdn.jsdelivr.net/npm/@flipperdotfamily/widget@0/dist/cdn/flipper-host.js) and call the global:

<div id="flipper"></div>
<script src="https://flipper.family/embed/flipper-host.js"></script>
<!-- or https://cdn.jsdelivr.net/npm/@flipperdotfamily/widget@0/dist/cdn/flipper-host.js -->
<script>
  FlipperEmbedHost.mountFlipperIframe({
    container: "#flipper",
    provider: window.ethereum,
    params: { theme: "auto", partner: "acme" },
  });
</script>

The raw protocol

Writing your own host? Every message is a JSON object with v: 1 and a source: "flipper" from the embed, "flipper-host" from you. Ignore anything else.

The embed may send these wallet methods, and refuses anything else before it reaches you:

• eth_accounts
• eth_chainId
• eth_requestAccounts
• eth_sendTransaction
• wallet_switchEthereumChain
• wallet_addEthereumChain
• wallet_watchAsset
• wallet_getCapabilities
• wallet_sendCalls
• wallet_getCallsStatus

The three EIP-5792 methods are optional. Answer 4200 and the widget falls back to sequential transactions. Transactions arrive fully specified (gas, EIP-1559 fees) and already simulated, so forward them unchanged. A minimal host:

const EMBED = "https://flipper.family";
// <iframe id="flipper" src="https://flipper.family/embed?partner=acme&hostOrigin=…">
const iframe = document.querySelector("iframe#flipper");
const provider = window.ethereum;
const send = (m) =>
  iframe.contentWindow.postMessage({ v: 1, source: "flipper-host", ...m }, EMBED);
const pushWallet = async () =>
  send({
    type: "wallet",
    accounts: await provider.request({ method: "eth_accounts" }),
    chainId: await provider.request({ method: "eth_chainId" }),
  });

window.addEventListener("message", async (e) => {
  if (e.source !== iframe.contentWindow || e.origin !== EMBED) return; // only our iframe
  const m = typeof e.data === "string" ? JSON.parse(e.data) : e.data;
  if (m?.v !== 1 || m.source !== "flipper") return;

  if (m.type === "rpc") {
    try {
      const result = await provider.request({ method: m.method, params: m.params });
      send({ type: "rpc-result", id: m.id, result });
    } catch (err) {
      const error = { code: err.code ?? -32603, message: err.message ?? "Request failed" };
      send({ type: "rpc-error", id: m.id, error });
    }
  } else if (m.type === "event") {
    if (m.name === "ready") pushWallet();
    if (m.name === "connect-request") openYourConnectModal(); // then pushWallet()
    if (m.name === "resize") iframe.style.height = m.data.height + "px";
  }
});
provider.on("accountsChanged", pushWallet);
provider.on("chainChanged", pushWallet);

Lifecycle, error codes, native transports and the full security model are in BRIDGE.md.

Mobile apps

Each mobile SDK loads the hosted embed (https://flipper.family/embed) in the platform's WebView and hands every wallet request to your app's wallet (WalletConnect / Reown AppKit, an embedded wallet or your own signer). The page never sees keys, and your wallet shows its own confirmation for every transaction.

Every SDK takes the same options as the embed URL (chain, token, tokens, theme, accent, radius, branding, partner, locale, compact, mode, fit, details, tagline), plus the full config object for white-labelling (brandName, brandLogo, coinImage, strings, …). Changes apply live, the widget sizes itself to its content, and it reports the same typed events as the web component.

import { FlipperWidget } from "@flipperdotfamily/react-native";
import { useAccount, useAppKit, useProvider } from "@reown/appkit-react-native";

export function Flip() {
  const { provider, providerType } = useProvider();
  const { address, chainId, isConnected } = useAccount();
  const { open } = useAppKit();

  return (
    <FlipperWidget
      wallet={isConnected && providerType === "eip155" ? provider : null}
      address={address ?? null}
      walletChainId={chainId ?? null} // number or CAIP-2 ("eip155:4663")
      theme="dark"
      accent="#ff5a1f"
      partner="acme"
      onConnectRequest={() => open()}
      onFlipSettled={(f) => console.log(f.outcome)}
    />
  );
}

FlipperWidget(
  wallet: myWallet, // a FlipperWallet; null = read-only
  config: const FlipperConfig(partner: 'acme'),
  theme: const FlipperTheme(mode: FlipperThemeMode.dark, accent: '#ff5a1f'),
  onConnectRequest: (_) => openMyConnectSheet(),
  onFlipSettled: (e) => debugPrint('flip ${e.flipId}: ${e.outcome}'),
)

FlipperWidgetView(
    config: FlipperConfig(partner: "acme"),
    theme: FlipperTheme(mode: .dark, accent: "#ff5a1f"),
    wallet: wallet
)
.onFlipperConnectRequest { _ in showConnectSheet = true }
.onFlipperFlipSettled { print($0.outcome ?? "") }

FlipperWidget(
    wallet = wallet, // null = read-only
    config = FlipperConfig(partner = "acme"),
    theme = FlipperTheme(mode = FlipperThemeMode.DARK, accent = "#ff5a1f"),
    onConnectRequest = { openConnect() },
    onFlipSettled = { e -> Log.i("flip", "${e.flipId} ${e.outcome}") },
)

Prefer a fully native UI? useFlipperHeadless() from @flipperdotfamily/react-native/headless gives you balances, previews and flip() on top of @flipperdotfamily/sdk.

The protocol is in BRIDGE.md, and each SDK's README covers wallet wiring, theming, events and troubleshooting. For a host of your own (Capacitor, Tauri, a custom WebView), implement the host side of the bridge described there.

Theming and white-label

Picker or single token

mode="picker" (the default) lets the user choose among listed tokens, and tokens narrows the list. mode="single" fixes one token and drops the picker, leaving a plain amount input with the token's logo and symbol beside it. Single mode needs token (an address or "ETH"), or the widget shows a configuration error rather than guessing. hidePicker still works as a deprecated alias.

<flipper-widget mode="single" token="0x…your token"></flipper-widget>

Headline and details

By default the widget shows only the coin, the amount with a small balance line, and the button. When a token's swap fees trim a flip's odds below usual, a quiet ↓ Odds 0.9 pts below usual appears beside the balance (Odds −0.9 pts when narrow). It shows the deviation, never the odds. Turn on details for win chance, payout and fee under the button. Set tagline for a headline under the coin: true for the built-in one, or your own text.

<flipper-widget details tagline="Double or nothing on Acme"></flipper-widget>

Any size

The widget lays out from its own box (container queries), not the viewport, scaling type, spacing and the coin fluidly. It tightens below about 300 px, and from 640 px the coin moves beside the form (the compact variant becomes a one-line bar from 960 px). Height follows the content, reported by resize events. fit="fill" takes the element's height too, for fixed-size cards, sidebars and full-bleed panels; the coin scales with the height, and extras drop away on short boxes. size (sm / md / lg) scales everything. The token picker is a sheet inside the widget, so it always fits.

<!-- a fixed-size card -->
<flipper-widget fit="fill" style="width: 320px; height: 520px"></flipper-widget>

<!-- fill a sidebar -->
<aside style="height: 100vh">
  <flipper-widget fit="fill" mode="single" token="ETH"></flipper-widget>
</aside>

Theme

Three layers, and later ones win:

1. CSS custom properties from your stylesheet: flipper-widget { --flipper-accent: #ff5a1f; }.
2. The theme object (the theme property, typed FlipperTheme), plus the accent and radius shorthands.
3. ::part() for anything else.

Playground

The real widget, loaded from /embed/flipper-widget.js. Change the settings and copy the code below.

<script src="https://cdn.jsdelivr.net/npm/@flipperdotfamily/widget@0/dist/cdn/flipper-widget.js"></script>

<flipper-widget
  theme="dark"
  partner="acme"
></flipper-widget>

<script>
  const flipper = document.querySelector("flipper-widget");
  flipper.provider = window.ethereum; // or your wallet kit's EIP-1193 provider
</script>

import { FlipperWidget } from "@flipperdotfamily/react";

<FlipperWidget
  provider={provider}
  theme="dark"
  partner="acme"
  onConnectRequest={openConnectModal}
/>

import { mountFlipperIframe } from "@flipperdotfamily/widget/host";

mountFlipperIframe({
  container: "#flipper",
  provider: window.ethereum,
  params: { theme: "dark", partner: "acme" },
});

The theme object

Every field is optional; unset colours keep flipper's palette for the current mode.

flipper.theme = {
  mode: "auto",                  // "light" | "dark" | "auto" (follows prefers-color-scheme)
  accent: "#ff5a1f",             // text on it is picked for contrast (or set accentText)
  background: "#fff8f2", surface: "#fff", field: "#fbefe6", border: "#0000001a",
  text: "#1b1109", textMuted: "#1b110999", textSubtle: "#1b110966",
  win: "#c77700", loss: "#d23a2e",
  radius: 16,                    // px or any CSS length; inner controls scale from it
  fontFamily: "inherit",         // use the host page's font
  displayFontFamily: "Georgia, serif", monoFontFamily: "ui-monospace, monospace",
  density: "compact",            // "compact" | "comfortable" | "spacious"
  coinSize: 96, shadow: "none", borderWidth: 0, maxWidth: "none",
  dark: { background: "#140c06" }, // per-mode overrides (also: light)
};

CSS custom properties

Set them on the element from your CSS. Colours default to flipper's palettes, and accentText is computed for contrast when you set only accent. The --flipper-check* properties colour the picker's checkmarks and have no theme key. --flipper-check is for tokens flipper whitelists (it follows the accent), and --flipper-check-launchpad for verified launchpad launches.

/* layer 1: custom properties from your stylesheet */
flipper-widget {
  --flipper-accent: #ff5a1f;
  --flipper-radius: 12px;
  --flipper-font: "Inter", system-ui, sans-serif;
}

/* layer 3: ::part() for anything else */
flipper-widget::part(cta) { text-transform: uppercase; letter-spacing: 0.04em; }
flipper-widget::part(card) { border: 2px solid #1b1109; box-shadow: 6px 6px 0 #1b1109; }

::part() hooks

Style anything the theme doesn't cover with flipper-widget::part(name):

• root
• card
• header
• brand
• account
• coin
• status
• result
• payout
• field
• token-button
• amount-input
• max-button
• balance
• odds
• note
• cta
• details
• footer
• picker
• picker-search
• picker-row
• check
• check-launchpad
• trigger
• modal

Variants and density

card (the default) has a header, the 3D coin and the form. compact puts a small coin inline with denser spacing, for sidebars and feeds. button renders a trigger that opens the card in a native <dialog> (el.open() / el.close() work too). Separately, theme.density sets the spacing scale: compact, comfortable (default) or spacious. The layout follows the widget's own width down to 280 px.

<!-- default: header, 3D coin, form -->
<flipper-widget variant="card"></flipper-widget>

<!-- small inline coin, denser -->
<flipper-widget variant="compact"></flipper-widget>

<!-- a trigger that opens the card in a modal -->
<flipper-widget variant="button" button-label="Flip FLIPPER"></flipper-widget>

Fonts

The widget doesn't download fonts. It asks for Manrope (UI), Satoshi (headlines) and JetBrains Mono (numbers), and falls back to system stacks if your page hasn't loaded them. fontFamily: "inherit" uses your page's font, and displayFontFamily and monoFontFamily set the other two.

White-label

branding="false" removes flipper's marks (the header dolphin, the dolphin and fluke coin faces, and the “Powered by” footer). Then add your name (brandName), logo (brandLogo, square, 64 px or more), coin faces (coinImage, coinImageTails; with branding off, the logo doubles as heads), accent and copy (strings).

<flipper-widget
  branding="false"
  brand-name="Acme"
  brand-logo="https://acme.example/logo.svg"
  coin-image="https://acme.example/coin-heads.png"
  coin-image-tails="https://acme.example/coin-tails.png"
  accent="#ff5a1f"
  tagline="Double or nothing on Acme"
  partner="acme"
></flipper-widget>

Strings and locales

locale picks a built-in table (en, es); strings overrides any key on top of it. {placeholders} are filled in at render time.

flipper.locale = "es"; // built-in: "en" (default), "es"; "es-MX" falls back to "es"
flipper.strings = {
  flip: "Flip {amount} {symbol}!",      // {placeholders} are filled in at render time
  won: "Nice.",
  tagline: "Double or nothing on Acme", // shown with tagline={true} (off by default)
};

Config and events

Properties take typed values; attributes are kebab-case strings. Every option is optional. The same names are the framework wrappers' props and the fields of the embed's config.

Options

Methods

Events

CustomEvents dispatched on the element. They don't bubble, so listen on the element itself. Every detail is JSON-safe (amounts are wei as decimal strings), and every payload except resize carries your partner. The embed bridge sends the same payloads. In TypeScript, onFlipperEvent from @flipperdotfamily/widget types the detail and avoids the clash between ready / error / resize and DOM event types:

import { onFlipperEvent } from "@flipperdotfamily/widget";

const seen = new Set<string>();
const off = onFlipperEvent(flipper, "flip-settled", (d) => {
  if (d.pending) return; // WinPending: a final flip-settled for this flipId follows
  if (seen.has(d.flipId)) return;
  seen.add(d.flipId);
  track(d.outcome, d.payout, d.partner);
});
// later: off();

Event names per framework

Headless SDK

@flipperdotfamily/sdk is what the widget runs on: a framework-agnostic viem client for deployments, previews, flips, native ETH, listing and settlement. Use it for your own UI, a script or a backend. Its only peer dependency is viem@^2.

npm i @flipperdotfamily/sdk viem

import {
  createFlipperClient, describeSettlement, flipperChain,
  resolveDeployment, walletClientFromProvider,
} from "@flipperdotfamily/sdk";
import { createPublicClient, http, parseUnits } from "viem";

const deployment = await resolveDeployment({ chainId: 4663 }); // Robinhood Chain: addresses, RPC, API
const chain = flipperChain(deployment);
const publicClient = createPublicClient({ chain, transport: http(deployment.rpcUrl) });
const [account] = await window.ethereum.request({ method: "eth_requestAccounts" });
const walletClient = walletClientFromProvider(window.ethereum, chain, account);

const flipper = createFlipperClient({
  publicClient,
  walletClient,
  addresses: deployment.addresses,
});

const house = await flipper.house();
const { flipId, receipt } = await flipper.flip({
  token: house.flipper,          // $FLIPPER; any listed token works
  amount: parseUnits("100", 18),
  approve: "max",                // default "exact"
  // previewing → approving → approve-sent → signing → flip-sent → requested
  onStep: (s) => console.log(s.step),
});

const settled = await flipper.waitForSettlement(flipId, { fromBlock: receipt.blockNumber });
const copy = describeSettlement(settled, { symbol: "FLIPPER", decimals: 18 });
console.log(copy.headline, copy.detail); // "You won." …

1. 1

   resolveDeployment

   Returns the chain's addresses, RPC and API. Explicit addresses (with house and lens) win and nothing is fetched; otherwise it reads the live manifest (deploymentUrl: null forbids that).
2. 2

   flip()

   Takes a fresh preview and throws a FlipperError if the house would reject. Then it approves if the allowance is short, simulates and sends flip with the preview's win chance as the minimum and a 5-minute deadline, and returns the flipId. The randomness fee goes with 20% headroom, which the house refunds.
3. 3

   waitForSettlement

   Resolves when the flip leaves Pending. waitForResolution follows a WinPending flip until upkeep pays it, and describeSettlement gives player-facing copy for every status.

Native ETH

The house flips WETH. flipEth wraps and flips in one call. If the wallet supports atomic batching (EIP-5792), wrap, approve and flip go out as one wallet_sendCalls with one confirmation. Otherwise they're sequential (batch: "never" forces that). If WETH isn't listed yet it throws with details.errorName === "WethNotListed", and anyone can list it.

import { parseEther } from "viem";

const res = await flipper.flipEth({
  amount: parseEther("0.01"),
  approve: "max",
  // previewing → (batch-signing → batch-sent) or
  // (wrapping → wrap-sent → approving → approve-sent → signing → flip-sent) → requested
  onStep: (s) => console.log(s.step),
});
console.log(res.batched); // true: wrap + approve + flip went out as one EIP-5792 batch

const { flipId, receipt } = res;
const settled = await flipper.waitForSettlement(flipId, { fromBlock: receipt.blockNumber });
// winnings arrive as WETH: flipper.unwrapWeth(amount) turns them back into ETH

Listing a token

Only qualifying tokens can be listed: tokens and pools flipper whitelists, or a launchpad's launches vouched for by its own onchain verifier. Each venue has its own route adapter:

You don't call the adapters directly. The flipper API knows each token's best pool, and checkListing / list pick the venue.

import { createFlipperApi, listingTargetFromApi } from "@flipperdotfamily/sdk";

// partner is sent as the X-Flipper-Partner header
const api = createFlipperApi({ url: deployment.apiUrl!, partner: "acme" });
const page = await api.tokens({ q: "tsla", limit: 40 }); // { tokens, sections, total, next }
const { token } = await api.token(page.tokens[0].address); // one token, every eligible pool

// { venue: "v4" | "v3", … } from the token's best pool; null without one
const target = listingTargetFromApi(token);
if (target) {
  // the adapter's check(), then a dry run; never throws
  const check = await flipper.checkListing(target);
  if (check.ok) await flipper.list(target, { onSent: (hash) => console.log("sent", hash) });
  else console.log(check.reason); // plain English; also check.code, check.routeCostBps
}

createFlipperApi makes only public, CORS-open reads with no credentials. They're rate-limited to 20 per second per end-user IP, so debounce searches.

Building your own UI

The widget's own building blocks: previews (odds, fee and whether the house accepts the stake), the odds-shift note, plain-English reject reasons, the displayed randomness fee and the largest stake at full odds. Every write rethrows a FlipperError with a plain-English message, and describeError(err) does the same for any viem error.

import { formatBps, oddsShift, rejectReason } from "@flipperdotfamily/sdk";

// eth_call: odds, fee, and whether the house accepts this stake
const pv = await flipper.preview(token, amount);
if (pv.code !== 0) showError(rejectReason(pv.code, { symbol })?.message);

// costly routes trim the odds, never the payout (from ~8% at the launch edge)
// terms: the base odds and payout now (the edge comes down as the protocol grows)
const { terms } = await flipper.house();
const shift = oddsShift(pv, terms);
showOdds(formatBps(pv.winChanceBps), shift.shifted ? shift.message : null);

// the fee to display; flip() sends it padded and the house refunds the rest
const fee = await flipper.displayRandomnessFee(token);
// the largest stake that still gets the base odds
const { amount: fullOdds } = await flipper.maxStake(token, balance, true);

In React, useFlipperClient from @flipperdotfamily/react builds the same client from a provider or wallet client (provider, walletClient, chainId, rpcUrl, addresses, deploymentUrl, all optional):

"use client";
import { useFlipperClient } from "@flipperdotfamily/react";

const { client, deployment, chain, loading, error } = useFlipperClient({
  provider,
  chainId: 4663, // Robinhood Chain
});

Everything else (holder rewards, claims, token discovery, gas-aware fees, ABIs) is in the SDK README.

Chains and contracts

On any other chain the widget says it isn't live there yet. Addresses, RPCs and API URLs come from the deployment manifest at flipper.family/embed/deployment.json, which the widget and resolveDeployment() read unless you pin addresses.

Security

• The wallet stays with you. The widget and the embed never hold keys and never ask for message signatures. Every transaction goes through your wallet's own confirmation.
• Simulated first. Every transaction is simulated before it's sent, and flips carry a minimum win chance and a deadline, so a flip can't land at worse odds than shown.
• Pin what you trust. Addresses come from addresses or from the manifest over HTTPS. Pin addresses (and rpcUrl) if you'd rather not trust the manifest at runtime.
• No credentials. API calls send no cookies, keys or tokens, only X-Flipper-Partner. Your partner id is public by design.
• Iframes. Pass hostOrigin (mountFlipperIframe does) so the embed only exchanges messages with your origin. On your side, check event.source === iframe.contentWindow and event.origin === "https://flipper.family", and refuse wallet methods outside the bridge's list with 4200.
• Content Security Policy. The web component needs connect-src for the chain's RPC and the flipper API (and flipper.family for the manifest, unless you pin addresses), and img-src for token logos. The CDN script needs script-src cdn.jsdelivr.net, or self-host the file. The iframe embed needs only frame-src flipper.family (and script-src for flipper-host.js if you load it from a URL).
• Native apps. Keep the WebView on flipper.family/embed and open other links in the system browser; the mobile packages do this for you.

FAQ

import { FlipperWidget } from "@flipperdotfamily/widget/element"; // the class, not registered

customElements.define("acme-flip", class extends FlipperWidget {});
// <acme-flip partner="acme"></acme-flip>