> 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. **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](/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