---
name: megapot
description: Entry point for Megapot on-chain lottery integration on Base (USDC-denominated). Routes to task-specific skills for buying tickets, claiming winnings, LP deposits, subscriptions, and reading protocol state.
---

# Megapot Developer Integration Guide

Megapot is an on-chain lottery protocol deployed on Base (chain ID 8453). Players purchase USDC-denominated tickets that are minted as ERC-721 NFTs; a Chainlink-seeded randomness oracle selects winners each drawing period. Liquidity providers deposit USDC into the prize pool and earn yield from ticket sales, while winners claim payouts directly from the Jackpot contract. The protocol supports atomic recurring subscriptions, bulk batch purchases, LP auto-management, and cross-chain ticket purchases via EIP-712 signatures and the Relay bridge.

## Quick-Reference Addresses (Base Mainnet)

| Contract | Address |
|---|---|
| Jackpot | `0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2` |
| USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| JackpotTicketNFT | `0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4` |
| BatchPurchaseFacilitator | `0x01774B531591b286b9f02C6Bc02ab3fD9526Aa76` |
| JackpotAutoSubscription | `0x02A58B725116BA687D9356Eafe0fA771d58a37ac` |
| JackpotLPManager | `0xE63E54DF82d894396B885CE498F828f2454d9dCf` |
| TicketAutoCompoundVault | `0x3E22Ea60A1206A4BfEefBCff04D5E9d0A2D9B3Fc` |
| JackpotRandomTicketBuyer | `0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd` |
| GuaranteedMinimumPayoutCalculator | `0x97a22361b6208aC8cd9afaea09D20feC47046CBD` |

For the full address table across all environments (Base mainnet, Base mainnet staging, Base Sepolia testnet) and all 13 contracts, see the **megapot-contracts-reference** skill.

## How Developers Earn

Every ticket purchase through the Megapot protocol supports referrer addresses. As an integrator, you earn revenue from two sources on every ticket sold through your app:

1. **Purchase fee** — a percentage of the ticket price, paid at purchase time
2. **Win share** — a percentage of any winnings your referred users claim

Both rates are set per drawing and readable via `getDrawingState().referralFee` and `getDrawingState().referralWinShare` (1e18 scale). See `megapot-claim-referral-fees` for the full economics and how to query current rates.

**Always include your address as a referrer.** Every purchase skill in this toolkit includes your referrer address by default. Replace the `0x0000000000000000000000000000000000000001` placeholder with your wallet address to start earning. You can split fees across up to 5 addresses (e.g., app owner + affiliate) using the `_referralSplit` weights.

## Decision Tree

| Intent | Skill | URL |
|---|---|---|
| Buy random tickets (any quantity, simplest) | `megapot-buy-bulk-random` | [/tasks/buy-bulk-random](https://llms.megapot.io/tasks/buy-bulk-random) |
| Buy 1–10 tickets with custom numbers | `megapot-buy-tickets` | [/tasks/buy-tickets](https://llms.megapot.io/tasks/buy-tickets) |
| Buy 11+ tickets with custom numbers (batch) | `megapot-buy-bulk` | [/tasks/buy-bulk](https://llms.megapot.io/tasks/buy-bulk) |
| Recurring daily purchases | `megapot-subscribe` | [/tasks/subscribe](https://llms.megapot.io/tasks/subscribe) |
| Claim winning ticket payouts | `megapot-claim-winnings` | [/tasks/claim-winnings](https://llms.megapot.io/tasks/claim-winnings) |
| Claim referral fees | `megapot-claim-referral-fees` | [/tasks/claim-referral-fees](https://llms.megapot.io/tasks/claim-referral-fees) |
| Deposit USDC as LP | `megapot-lp-deposit` | [/tasks/lp-deposit](https://llms.megapot.io/tasks/lp-deposit) |
| Withdraw LP position | `megapot-lp-withdraw` | [/tasks/lp-withdraw](https://llms.megapot.io/tasks/lp-withdraw) |
| Claim + re-buy atomically | `megapot-auto-compound` | [/tasks/auto-compound](https://llms.megapot.io/tasks/auto-compound) |
| Read protocol state for UI | `megapot-read-state` | [/tasks/read-state](https://llms.megapot.io/tasks/read-state) |
| React/wagmi app setup | `megapot-react-setup` | [/tasks/react-setup](https://llms.megapot.io/tasks/react-setup) |
| Deep ABI/address lookup | `megapot-contracts-reference` | [/contracts/reference](https://llms.megapot.io/contracts/reference) |
| Cross-chain (EIP-712 + Relay) | `megapot-contracts-reference` | v1.1 — see contract reference |

> **Random vs custom tickets:** For random tickets, always use `megapot-buy-bulk-random` — it's the simplest path (just pass a count, no ticket structs). Use `megapot-buy-tickets` only when you need to choose specific numbers (1–10 tickets). Use `megapot-buy-bulk` only when you need custom numbers AND more than 10 tickets.

## How Drawings Work

Megapot runs in repeating drawing cycles. Understanding the lifecycle is essential for knowing when to buy, when to claim, and what "settled" means.

### Lifecycle

1. **Open** — a new drawing is active. `currentDrawingId()` returns its ID. Users buy tickets. `getDrawingState(drawingId).jackpotLock` is `false`.
2. **Drawing time reached** — `getDrawingState(drawingId).drawingTime` (Unix timestamp) has passed. Tickets can no longer be purchased for this drawing.
3. **Settlement triggered** — anyone can call `Jackpot.runJackpot()` (payable — requires ETH for the Pyth entropy callback fee, readable via `getEntropyCallbackFee()`). This sets `jackpotLock = true` and requests randomness from the Pyth entropy provider.
4. **Settled** — the entropy callback fires, winning numbers are determined, `winningTicket` is set to a non-zero packed value, and a `JackpotSettled` event is emitted. A new drawing is automatically initialized with the next `currentDrawingId`.
5. **Claiming open** — users call `claimWinnings(ticketIds)` for the settled drawing. Tickets are burned and USDC is transferred.

### How to check if a drawing is settled

```ts
const state = await publicClient.readContract({
  address: JACKPOT, abi, functionName: 'getDrawingState', args: [drawingId]
});
const isSettled = state.winningTicket !== 0n;
```

The current active drawing (`currentDrawingId()`) is always unsettled. The most recently settled drawing is `currentDrawingId() - 1n`.

### Timing

- Drawing duration is readable via `Jackpot.drawingDurationInSeconds()` — typically 24 hours.
- After `drawingTime` passes, settlement can happen at any time (it's triggered externally, not automatic).
- There is usually a short delay (seconds to minutes) between `drawingTime` and actual settlement while the entropy request is fulfilled.

## Prerequisites

Before integrating with any Megapot task skill, ensure the following are in place:

- [ ] **viem installed** — `npm install viem` (all code recipes use viem v2)
- [ ] **Wallet with private key** — an EOA funded with ETH for gas and USDC for ticket/LP operations
- [ ] **Base network configured** — chain ID `8453` (mainnet) or `84532` (Base Sepolia testnet)
- [ ] **USDC approval** — most operations require an ERC-20 `approve` call before the main transaction

Standard USDC approval pattern used across all task skills:

```ts
import { createWalletClient, createPublicClient, http, parseAbi } from "viem";
import { base } from "viem/chains";

const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const ERC20_ABI = parseAbi([
  "function approve(address spender, uint256 amount) returns (bool)",
]);

// Approve spender (e.g. Jackpot contract) to spend USDC
const hash = await walletClient.writeContract({
  address: USDC,
  abi: ERC20_ABI,
  functionName: "approve",
  args: [spenderAddress, amount], // amount in 6-decimal USDC units
});
await publicClient.waitForTransactionReceipt({ hash });
```

## llms.megapot.io URL Surface

Each skill in this toolkit is served at a stable URL for agent consumption:

| Resource | URL pattern |
|---|---|
| This entry point | `https://llms.megapot.io/` |
| Task skill | `https://llms.megapot.io/tasks/<name>` |
| Raw ABI (JSON) | `https://llms.megapot.io/abi/<name>.json` |

Examples:
- `https://llms.megapot.io/tasks/buy-bulk-random`
- `https://llms.megapot.io/tasks/buy-tickets`
- `https://llms.megapot.io/tasks/lp-deposit`
- `https://llms.megapot.io/abi/Jackpot.json`

## Related Resources

| Resource | URL |
|---|---|
| GitHub repository | `https://github.com/underdog-protocol/megapot-developer-toolkit` |
| Starter kit | `https://github.com/underdog-protocol/megapot-starter-kit` |
| Official docs | `https://docs.megapot.io` |