> For the complete documentation index, see [llms.txt](https://docs.megapot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.megapot.io/build-on-megapot/add-to-your-site.md).

# 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.

{% hint style="success" %}
**See it working first.** The full reference app is live at [**demo.megapot.io**](https://demo.megapot.io/) against Base mainnet. Click through buy, claim, and history before you write a line of code.
{% endhint %}

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

* [**Wire one flow**](#weight-a-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**](#weight-b-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

{% hint style="warning" %}
**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. **Your `_source` tag** in `_source`: one `bytes32` label for your app, the same on every call. Once allow-listed, it shows your app's name and icon on megapot.io results.

These are independent: the referrer wallet moves money, the source tag is attribution only and never affects payments. Miss the referrer wallet and you earn nothing. Miss the source tag and your app won't show up on megapot.io. See [Get Listed](/build-on-megapot/get-listed.md) to get your tag allow-listed. See [Referrals & Attribution](/build-on-megapot/build/referrals-and-attribution.md) for the full model.
{% endhint %}

***

## 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](/build-on-megapot/build/protocol-reference.md). 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.

```typescript
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`](https://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](/build-on-megapot/build/protocol-reference.md).

### 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](/build-on-megapot/build/claiming.md).

{% hint style="info" %}
**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](https://llms.megapot.io) for AI-ready viem and wagmi recipes, and use the [Protocol Reference](/build-on-megapot/build/protocol-reference.md) for addresses and full signatures.
{% endhint %}

***

## 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](https://demo.megapot.io/). MIT licensed.

```bash
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**](https://github.com/coordinationlabs/megapot-starter-kit): quickstart and the three deploy shapes
* [**docs/CUSTOMIZE.md**](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/docs/CUSTOMIZE.md): every rebrand seam in one checklist
* [**docs/ARCHITECTURE.md**](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/docs/ARCHITECTURE.md): API/RPC split, polling cadence, decisions
* [**Live demo**](https://demo.megapot.io/): the running kit on Base mainnet

***

Building with an AI assistant? Point it at [llms.megapot.io](https://llms.megapot.io) and it loads the right skills and recipes itself.

***

## Next

* [Start Here](/build-on-megapot/start-here.md): the lay of the land
* [Build on the protocol](/build-on-megapot/build.md): the deeper integration path
* [Referrals & Attribution](/build-on-megapot/build/referrals-and-attribution.md): how the money and the source tag work
* [Protocol Reference](/build-on-megapot/build/protocol-reference.md): addresses and full method signatures
* [Pull data](/build-on-megapot/pull-data.md): the read-only Data API