---
name: megapot-starter-kit
description: Forkable, white-label React + wagmi reference frontend for Megapot on Base (USDC). Implementation companion to the rest of this toolkit — shows how every task skill composes into a working five-page app. Fork, rebrand, ship. Live at https://demo.megapot.io/.
---

# Megapot Starter Kit

## What this is

A five-page React + wagmi reference frontend for the Megapot on-chain
lottery on Base. Forkable under MIT, white-label-ready, and live at
[**demo.megapot.io**](https://demo.megapot.io/) for one-click
verification of intended behavior.

The kit is the *implementation* companion to this skills toolkit. Every
task skill here teaches one protocol-side flow (calldata, return shape,
edge cases); the kit shows how those flows compose into a working app
with phase-aware polling, event-driven invalidation, exact-allowance
approvals, and a typed Data API client.

## When to use this skill vs. individual task skills

| You're... | Use |
|---|---|
| Building a new Megapot-powered app from scratch | This skill — fork the kit, rebrand, ship |
| Integrating one Megapot flow into an existing app | The matching task skill (`tasks/buy-tickets`, `tasks/claim-winnings`, etc.) — copy the recipe in |
| Debugging an integration against known-good behavior | This skill — diff your app against the kit's hook for that flow, or point a user at https://demo.megapot.io/ to compare |
| Looking up an address or ABI | `contracts/reference` skill |
| Wiring off-chain reads (rounds, wallet history, leaderboards) | `data-api` skill — the kit's `src/lib/api.ts` is the canonical typed client |

## Fork in 5 minutes

```bash
git clone https://github.com/coordinationlabs/megapot-starter-kit
cd megapot-starter-kit
pnpm setup    # copies .env.example → .env and installs dependencies
# Set VITE_REFERRER_ADDRESS in .env to your wallet (earns referral fees)
pnpm dev      # http://localhost:5173
```

The kit ships with a dead-address referrer default (`0x…dEaD`) so a
fresh fork runs end-to-end with zero config — but any fees earned on
that address are unrecoverable. A dev-mode boot warning fires while
`VITE_REFERRER_ADDRESS` is still the default (and while `TICKET_SOURCE`
in `src/config/contracts.ts` is unchanged), so you can't accidentally
ship without attribution. Production builds stay silent.

Optional `.env` keys (both recommended for non-trivial deploys):

- `VITE_MEGAPOT_API_KEY` — mint at [megapot.io/dashboard](https://megapot.io/dashboard) to lift the anonymous Data API tier (10/min, 500/day) to the partner tier (60/min, 10K/day)
- `VITE_WALLETCONNECT_PROJECT_ID` — without it, injected wallets (MetaMask, Coinbase Wallet) still work but the WalletConnect QR modal doesn't

Full env reference with rationale for each variable:
[`.env.example`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/.env.example).

## What's wired up

| Page | What it does | Skill(s) demonstrated | Files to read |
|---|---|---|---|
| Home | Live drawing state, countdown, prize-tier projection | `tasks/read-state` | `src/pages/Home.tsx`, `src/hooks/useJackpotState.ts`, `src/hooks/usePrizeTiers.ts` |
| Play | Buy tickets — single, bulk, or subscription | `tasks/buy-tickets`, `tasks/buy-random`, `tasks/buy-bulk`, `tasks/subscribe` | `src/pages/Play.tsx`, `src/hooks/useBuyTickets.ts`, `src/hooks/useBulkPurchase.ts`, `src/hooks/useSubscribe.ts` |
| Tickets | Your tickets, unclaimed wins, claim flow, referral fee claim | `tasks/claim-winnings`, `tasks/claim-referral-fees`, `data-api` | `src/pages/Tickets.tsx`, `src/hooks/useClaimWinnings.ts`, `src/hooks/useClaimReferralFees.ts`, `src/components/tickets/*` |
| LP | USDC deposit + two-step withdraw (opt-in via `LP_ENABLED`) | `tasks/lp-deposit`, `tasks/lp-withdraw` | `src/pages/LP.tsx`, `src/hooks/useLpDeposit.ts`, `src/hooks/useLpWithdraw.ts`, `src/components/lp/*` |
| History | Paginated past rounds with winners | `data-api` | `src/pages/History.tsx`, `src/hooks/useRoundsList.ts`, `src/components/history/DrawingList.tsx` |

Cross-cutting:

- All on-chain reads / writes go through wagmi hooks per `tasks/react-setup`.
- All Data API reads share `src/lib/api.ts` (typed client, retry, `QK` query-key constants).
- USDC approvals are exact-amount via `src/components/common/ApprovalButton.tsx` (smaller blast radius than `maxUint256`).

## Toolkit → Starter Kit cross-reference index

Inverse of the per-skill `## See in practice` blocks. Use this to jump
from a task skill to its kit implementation, or vice versa.

| Toolkit skill | Kit file(s) |
|---|---|
| `tasks/buy-tickets` | [`src/hooks/useBuyTickets.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useBuyTickets.ts), [`src/pages/Play.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/pages/Play.tsx) |
| `tasks/buy-random` | `src/hooks/useBuyTickets.ts` — kit generates random picks client-side then calls `Jackpot.buyTickets`. Note: the kit doesn't use `JackpotRandomTicketBuyer`; for pure quick-pick that contract is the recommended path (see the buy-random skill) |
| `tasks/buy-bulk` | [`src/hooks/useBulkPurchase.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useBulkPurchase.ts), [`src/pages/Play.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/pages/Play.tsx) |
| `tasks/subscribe` | [`src/hooks/useSubscribe.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useSubscribe.ts), [`src/components/tickets/ActiveSubscription.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/components/tickets/ActiveSubscription.tsx) |
| `tasks/claim-winnings` | [`src/hooks/useClaimWinnings.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useClaimWinnings.ts), [`src/components/tickets/UnclaimedWins.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/components/tickets/UnclaimedWins.tsx) |
| `tasks/claim-referral-fees` | [`src/hooks/useClaimReferralFees.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useClaimReferralFees.ts), [`src/components/tickets/ClaimReferralFees.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/components/tickets/ClaimReferralFees.tsx) |
| `tasks/lp-deposit` | [`src/hooks/useLpDeposit.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useLpDeposit.ts), [`src/components/lp/DepositForm.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/components/lp/DepositForm.tsx) |
| `tasks/lp-withdraw` | [`src/hooks/useLpWithdraw.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useLpWithdraw.ts), [`src/components/lp/WithdrawTwoStep.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/components/lp/WithdrawTwoStep.tsx) |
| `tasks/auto-compound` | Not shipped in the kit; closest pattern is `useClaimWinnings.ts` |
| `tasks/read-state` | [`src/hooks/useJackpotState.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/useJackpotState.ts), [`src/hooks/usePrizeTiers.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/hooks/usePrizeTiers.ts) |
| `tasks/react-setup` | [`src/main.tsx`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/main.tsx), [`src/config/wagmi.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/config/wagmi.ts) |
| `data-api` | [`src/lib/api.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/lib/api.ts) + every `src/hooks/use*Round*.ts` and `useWallet*.ts` |
| `contracts/reference` | [`src/config/contracts.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/src/config/contracts.ts) (chain-resolved address table) |

## Reading the kit as an agent

Every file in `src/` of the kit carries a JSDoc header with the
convention `@skill / @contract / @endpoint / @customize`. Read the
header first; you'll know what the file does, what protocol surface
it touches, and what's expected to be edited on a fork.

- **`@skill`** — link to the canonical skill on `llms.megapot.io` (this toolkit). Protocol-side semantics live there; the kit is the implementation pattern.
- **`@contract`** — names the on-chain function the file calls (e.g. `Jackpot.buyTickets`, `JackpotLPManager.lpDeposit`).
- **`@endpoint`** — names the Data API endpoint the file consumes (e.g. `GET /v1/rounds`).
- **`@customize`** — describes what's expected to change vs stay stable on a fork.

Two flat manifests that grep well:

- [`llms.txt`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/llms.txt) — file → purpose for every file in `src/`
- [`AGENTS.md`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/AGENTS.md) — the convention guide and where-to-start-by-goal map

When a `@skill` link appears in a file header, treat the linked skill
as source of truth for protocol-side behavior. The kit is the
implementation; the skill is the protocol.

## Customize / rebrand

The kit ships with nine ordered rebrand seams. Most forks only touch
brand identity + referrer attribution before shipping:

1. **Brand identity** — logo (`src/components/layout/BrandMark.tsx`), color scale (`tailwind.config.ts` → `theme.extend.colors.brand.primary`), copy (`src/config/copy.ts`), `index.html` head, wallet-connect app name
2. **Referrer attribution** — set `VITE_REFERRER_ADDRESS` in `.env` (dead-address default; dev-mode warning while unchanged). The `TICKET_SOURCE` analytics tag stays in `src/config/contracts.ts`
3. **Wallet provider** — RainbowKit is the default; swap to Privy / ConnectKit / vanilla wagmi by editing `src/config/wagmi.ts` + `src/main.tsx`
4. **Chain** — `VITE_CHAIN=mainnet | testnet` in `.env`; addresses auto-resolve in `src/config/contracts.ts`
5. **LP feature toggle** — `LP_ENABLED` in `src/config/contracts.ts` (default `false`; flip to expose LP page to users)
6. **API key safety** — three tiers (anonymous / browser key / proxy) per `.env.example`
7. **Allowance strategy** — exact-amount by default; one-line swap to `maxUint256` in `src/components/common/ApprovalButton.tsx`
8. **Disclaimer line** — `src/components/layout/DisclaimerLink.tsx` is the seam
9. **UI copy** — single source at `src/config/copy.ts`

Full checklist with rationale and decision links:
[`docs/CUSTOMIZE.md`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/docs/CUSTOMIZE.md).

## Deploy

`pnpm build` produces a static `dist/`. Pick once per fork:

| Tier | What | Setup |
|---|---|---|
| **Anonymous** | No key, no backend — any static host (Vercel static, Cloudflare Pages, GitHub Pages, S3 + CloudFront, Netlify) | Just deploy. 10/min, 500/day rate limit per IP. |
| **Browser key** | Higher tier (60/min, 10K/day); key in browser bundle | Set `VITE_MEGAPOT_API_KEY` in host env vars. Acceptable for the read-only Data API; rotate via dashboard if leaked. |
| **Proxy** | Key never reaches the browser; recommended for production keys | Set `MEGAPOT_API_KEY` server-side AND `VITE_API_BASE_URL=/api/megapot`; deploy [`server/proxy.ts`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/server/proxy.ts) (framework-agnostic Hono). |

Platform wrappers for the proxy:
- [Vercel Functions](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/examples/deploy-vercel-function.ts)
- [Cloudflare Workers](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/examples/deploy-cloudflare-worker.ts)

The kit detects `mpk_dev_*` keys in production builds and warns at boot, so a forker doesn't chase a 403 chain.

## Related

- [`entry-point`](https://llms.megapot.io/) — decision tree for all task skills
- [`tasks/react-setup`](https://llms.megapot.io/tasks/react-setup) — wagmi + RainbowKit provider boilerplate the kit follows
- [`data-api`](https://llms.megapot.io/data-api) — REST API the kit's `src/lib/api.ts` wraps
- [`contracts/reference`](https://llms.megapot.io/contracts/reference) — every address + ABI the kit uses
- Every `tasks/<name>` skill — protocol-side semantics for the matching `src/hooks/use<Name>.ts` in the kit

**Source of truth.** For protocol-side behavior — calldata layout,
event signatures, edge cases, gas considerations — the linked task
skill is canonical. The kit is one implementation pattern, not a
substitute for reading the underlying skill.