Add the Jackpot to Your Site

You already have a product. This page shows how to drop Megapot buy and claim into it, and earn fees on every ticket your users buy, without rebuilding your app around it.

See it working first. The full reference app is live at demo.megapot.io against Base mainnet. Click through buy, claim, and history before you write a line of code.

Pick the path that fits how much you want to build:

• Wire one flow: keep your own UI, call the contracts directly. Best when you want buy or claim inside an existing screen.

• Fork the starter kit: a complete five-page React app you rebrand and ship. Fastest path to a full lottery experience.

---

Earn on every purchase

Whichever path you choose, set two things on every purchase:

1. Your referrer wallet in _referrers: this is who gets paid (10% of ticket fees + 10% of winnings from referred play).

2. A _source tag in _source: a free-form bytes32 label for your own analytics.

These are independent: the referrer wallet moves money, the source tag is telemetry only and never affects payments. Miss the referrer wallet and you earn nothing. See Referrals & Attribution for the full model.

---

Weight A: Wire one flow

Keep your own UI. Call the contract that matches your scenario:

Scenario	Contract & method	Execution
Up to 10 custom-number tickets	Jackpot.buyTickets	Immediate
Random / quick-pick	JackpotRandomTicketBuyer.buyTickets	Immediate
More than 10 tickets	BatchPurchaseFacilitator.createBatchOrder	Keeper-executed
Recurring across drawings	JackpotAutoSubscription.createSubscription	Keeper-executed

Addresses and full signatures for all four are in the Protocol Reference. Each carries a trailing bytes32 _source and the _referrers / _referralSplit pair.

One representative flow: Jackpot.buyTickets

This is the common case: up to 10 custom tickets, minted immediately. The pattern (read price → approve USDC → call with referrer + source) is the same for the other three methods; only the contract and arguments change.

import { createPublicClient, createWalletClient, http, stringToHex } from "viem";
import { base } from "viem/chains";

const JACKPOT = "0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2";
const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";

// Your attribution: the wallet that earns, and your analytics label.
const REFERRER = "0x1111111111111111111111111111111111111111"; // your wallet
const SOURCE = stringToHex("mysite", { size: 32 });            // bytes32 tag

// 1. Read live drawing state for the ticket price and number ranges.
//    ballMax / bonusballMax come from chain: do NOT hardcode them.
const state = await publicClient.readContract({
  address: JACKPOT,
  abi: jackpotAbi,
  functionName: "getDrawingState",
});
const ticketPrice = state.ticketPrice; // USDC, 6 decimals

// 2. Build tickets: 5 unique normals in [1, ballMax], bonusball in [1, bonusballMax].
const tickets = [
  { normals: [7, 14, 21, 28, 30], bonusball: 12 },
  { normals: [3, 11, 19, 27, 29], bonusball: 8 },
];

// 3. Approve USDC to the Jackpot contract (the one receiving payment).
const totalCost = ticketPrice * BigInt(tickets.length);
await walletClient.writeContract({
  address: USDC,
  abi: usdcAbi,
  functionName: "approve",
  args: [JACKPOT, totalCost],
});

// 4. Buy. referrerSplit weights must sum to exactly 1e18.
await walletClient.writeContract({
  address: JACKPOT,
  abi: jackpotAbi,
  functionName: "buyTickets",
  args: [
    tickets,
    userAddress,          // _recipient: owns the ticket NFTs
    [REFERRER],           // _referrers: who gets paid
    [1000000000000000000n], // _referralSplit: 100% (1e18) to the one referrer
    SOURCE,               // _source: your bytes32 analytics tag
  ],
});
// Tickets are minted immediately.

Confirm the exact signature and ABI at llms.megapot.io/abi/Jackpot.txt before shipping.

Showing prize info

Read live values rather than hardcoding anything:

• Jackpot.getDrawingState() → current prize pool, ticketPrice, ballMax, bonusballMax, plus the live referralFee and referralWinShare rates (1e18 precision).

• GuaranteedMinimumPayoutCalculator (the PayoutCalculator) → expected per-tier payouts for display.

Both addresses are in the Protocol Reference.

Claiming winnings

Surface a claim in your UI and call Jackpot.claimWinnings(uint256[] _ticketIds) with the user's winning ticket IDs. For win-detection, auto-compound, and claiming your own referral fees, see Claim winnings & fees.

Don't re-narrate the whole protocol here. For batch orders, subscriptions, auto-compound, LP, and read-state multicalls, point your editor at llms.megapot.io for AI-ready viem and wagmi recipes, and use the Protocol Reference for addresses and full signatures.

---

Weight B: Fork the starter kit

Want a complete app, not a single flow? The Megapot Starter Kit is a five-page React + wagmi reference frontend (Home, Play, Tickets, LP, History) implementing every core flow. It's the exact app running at demo.megapot.io. MIT licensed.

git clone https://github.com/coordinationlabs/megapot-starter-kit
cd megapot-starter-kit
pnpm bootstrap  # copies .env.example -> .env and installs deps
# Set VITE_REFERRER_ADDRESS to your wallet, and your source tag, in .env
pnpm dev      # http://localhost:5173

Set VITE_REFERRER_ADDRESS to your wallet and the source tag in config, rebrand, and ship. A dev-mode warning fires while the referrer or source tag is still the placeholder, so you can't accidentally deploy without attribution.

The kit ships three API-key deployment shapes: anonymous (no key), browser key (VITE_MEGAPOT_API_KEY), or server proxy (key stays server-side). Pick once per fork.

Everything else lives in the repo, don't look for it here:

• Repository + README: quickstart and the three deploy shapes

• docs/CUSTOMIZE.md: every rebrand seam in one checklist

• docs/ARCHITECTURE.md: API/RPC split, polling cadence, decisions

• Live demo: the running kit on Base mainnet

---

Building with an AI assistant? Point it at llms.megapot.io and it loads the right skills and recipes itself.

---

Next

• Start Here: the lay of the land

• Build on the protocol: the deeper integration path

• Referrals & Attribution: how the money and the source tag work

• Protocol Reference: addresses and full method signatures

• Pull data: the read-only Data API