> 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/developers/starter-kit.md).

# Starter Kit

Fork our open-source reference frontend and ship a Megapot integration in an afternoon. The **Megapot Starter Kit** is a five-page React + wagmi app implementing every core flow — play, claim winnings, back the prize pool, and view round history.

{% hint style="success" %}
**See it before you fork.** The kit is running live at [**demo.megapot.io**](https://demo.megapot.io/) against Base mainnet. Click through every page, connect a wallet, and check the flows you'd want to ship.
{% endhint %}

***

## What's in the kit

| Page        | What it does                                          | What it demonstrates                                   |
| ----------- | ----------------------------------------------------- | ------------------------------------------------------ |
| **Home**    | Live drawing state, countdown, prize-tier projections | Phase-aware RPC polling + event subscriptions          |
| **Play**    | Buy tickets — single, bulk, or subscription           | All three ticket-purchase methods + USDC approval      |
| **Tickets** | Your tickets, unclaimed wins, claim flow              | RPC + Data API mix, claim batching, referral fee claim |
| **LP**      | Deposit + two-step withdraw                           | LP manager interaction + locked-drawing handling       |
| **History** | Paginated past rounds with winners                    | Data API rounds endpoint + cursor pagination           |

GitHub: [coordinationlabs/megapot-starter-kit](https://github.com/coordinationlabs/megapot-starter-kit). MIT licensed.

***

## Get an API key (optional but recommended)

The kit works without an API key on the **anonymous tier** (10/min, 500/day) — fine for local development and low-traffic deploys.

For production, mint a key at your [megapot.io dashboard](https://megapot.io/dashboard). The **partner tier** lifts rate limits to 60/min and 10K/day, plenty for most deploys.

There are three deployment shapes — pick once per fork:

| Shape           | Setup                                                                                            | Trade-off                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Anonymous**   | No key, no backend                                                                               | Lowest rate limit; works on any static host                                                                                 |
| **Browser key** | Set `VITE_MEGAPOT_API_KEY` in your host env vars                                                 | Higher tier; key ships in browser bundle (acceptable for the read-only Data API; rotate via dashboard if leaked)            |
| **Proxy**       | Set `MEGAPOT_API_KEY` server-side AND `VITE_API_BASE_URL=/api/megapot`; deploy `server/proxy.ts` | Key never reaches the browser; requires a backend (Vercel Functions + Cloudflare Workers wrappers in the kit's `examples/`) |

Full reference: the kit's [`.env.example`](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/.env.example) documents every variable with rationale.

***

## Get started (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
pnpm dev      # http://localhost:5173
```

That's it. The kit ships with a dead-address referrer default so a fresh fork runs out of the box, and a dev-mode warning fires while `VITE_REFERRER_ADDRESS` is unchanged (and while the `TICKET_SOURCE` analytics tag in `src/config/contracts.ts` is the placeholder), so you can't accidentally ship without attribution.

{% hint style="info" %}
**Optional `.env` keys** (both recommended for non-trivial deploys):

* `VITE_MEGAPOT_API_KEY` — lifts the anonymous Data API tier to partner tier (see above)
* `VITE_WALLETCONNECT_PROJECT_ID` — without it, injected wallets (MetaMask, Coinbase Wallet) still work but the WalletConnect QR modal doesn't. Free at [cloud.walletconnect.com](https://cloud.walletconnect.com).
  {% endhint %}

***

## Rebrand checklist

The kit ships with nine ordered rebrand seams. Most forks only touch the first two before shipping:

1. **Brand identity** — logo, color scale, copy, HTML head, wallet-connect app name
2. **Referrer attribution** — set `VITE_REFERRER_ADDRESS` in `.env` (dead-address default); the `TICKET_SOURCE` analytics tag stays in `src/config/contracts.ts`
3. **Wallet provider** — RainbowKit default; swap to Privy / ConnectKit / vanilla wagmi
4. **Chain** — `VITE_CHAIN=mainnet | testnet` in `.env`
5. **LP feature toggle** — `LP_ENABLED` in `src/config/contracts.ts` (default off)
6. **API key safety** — the three deployment shapes above
7. **Allowance strategy** — exact-amount default; one-line swap to `maxUint256`
8. **Disclaimer line** — `src/components/layout/DisclaimerLink.tsx`
9. **UI copy** — single source at `src/config/copy.ts`

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

***

## Building with an AI assistant?

{% hint style="info" %}
Point your agent at [**llms.megapot.io/starter-kit**](https://llms.megapot.io/starter-kit) for the orientation skill that maps every kit file to its protocol counterpart. Every file in the kit's `src/` carries a JSDoc header with `@skill / @contract / @endpoint / @customize` metadata so an agent dropped into the repo orients in one read.
{% endhint %}

See [AI Agent Skills](/developers/ai-agent-skills.md) for the full skills library and the one-line instruction to add to your assistant's config.

***

## Resources

* [**Live demo**](https://demo.megapot.io/) — running against Base mainnet
* [**GitHub repository**](https://github.com/coordinationlabs/megapot-starter-kit) — MIT licensed
* [**AI orientation skill**](https://llms.megapot.io/starter-kit) — for AI coding assistants
* [Architecture doc](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/docs/ARCHITECTURE.md) — API/RPC division, polling cadence, decisions
* [Customize doc](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/docs/CUSTOMIZE.md) — every rebrand seam in one checklist
* [Disclaimer](https://github.com/coordinationlabs/megapot-starter-kit/blob/main/docs/DISCLAIMER.md) — Infrastructure Participant notice
* [AI Agent Skills](/developers/ai-agent-skills.md) — full skills library at `llms.megapot.io`
* [Data API](/developers/data-api.md) — REST API the kit's `src/lib/api.ts` wraps
* [Add Megapot to Your Site](/developers/buy-tickets.md) — step-by-step integration walkthrough


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.megapot.io/developers/starter-kit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.