> ## Documentation Index
> Fetch the complete documentation index at: https://docs.megapot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocol Reference

> [!NOTE]
>
> **ABIs are served live, CORS-open, at `https://llms.megapot.io/abi/<Name>.json` and `.txt`.** Fetch them at build or runtime. Do not copy ABIs into your repo, they go stale. Use the contract addresses in the table below (verified on-chain on Base, chain 8453).

Everything Megapot does runs through one contract: **Jackpot**. The other contracts are either tokens it mints, the pool it draws from, or thin helpers that route a purchase into it. This page is the short version: addresses, the call signatures that matter, and the core concepts. For full method-by-method detail, fetch the ABI.

***

## Addresses (Base, chain 8453)

| Contract | Address |
| - | - |
| USDC | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/address/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) |
| Jackpot | [`0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2`](https://basescan.org/address/0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2) |
| JackpotTicketNFT | [`0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4`](https://basescan.org/address/0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4) |
| JackpotLPManager | [`0xE63E54DF82d894396B885CE498F828f2454d9dCf`](https://basescan.org/address/0xE63E54DF82d894396B885CE498F828f2454d9dCf) |
| GuaranteedMinimumPayoutCalculator | [`0x97a22361b6208aC8cd9afaea09D20feC47046CBD`](https://basescan.org/address/0x97a22361b6208aC8cd9afaea09D20feC47046CBD) |
| BatchPurchaseFacilitator | [`0xBA343479D98a1Ed333899999D95a7343B808a76F`](https://basescan.org/address/0xBA343479D98a1Ed333899999D95a7343B808a76F) |
| JackpotAutoSubscription | [`0x2694Bd48f3e6B4775943067DC842C93bf5F19DcD`](https://basescan.org/address/0x2694Bd48f3e6B4775943067DC842C93bf5F19DcD) |
| JackpotRandomTicketBuyer | [`0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd`](https://basescan.org/address/0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd) |
| TicketAutoCompoundVault | [`0xfa6a75366E0A9dF56d67E4B4141050b438DB2A5E`](https://basescan.org/address/0xfa6a75366E0A9dF56d67E4B4141050b438DB2A5E) |

> [!WARNING]
>
> `JackpotBridgeManager` and `ScaledEntropyProvider` are protocol internals: you do not call them directly and they are listed here by name only.

***

## Purchase signatures

The five purchase routes all carry a trailing `bytes32 _source` telemetry tag, plus the two claim calls:

```solidity theme={null}
// Up to 10 custom-number tickets, minted immediately.
Jackpot.buyTickets(
    Ticket[] _tickets,
    address _recipient,
    address[] _referrers,
    uint256[] _referralSplit,
    bytes32 _source
) returns (uint256[] ticketIds);

// Random / quick-pick, minted immediately.
JackpotRandomTicketBuyer.buyTickets(
    uint256 _count,
    address _recipient,
    address[] _referrers,
    uint256[] _referralSplit,
    bytes32 _source
);

// More than 10 tickets, keeper-executed.
BatchPurchaseFacilitator.createBatchOrder(
    address _recipient,
    uint256 _dynamicCount,
    Ticket[] _staticTickets,
    address[] _referrers,
    uint256[] _referralSplit,
    bytes32 _source
);

// Recurring across drawings, keeper-executed.
JackpotAutoSubscription.createSubscription(
    address _recipient,
    uint256 _days,
    uint256 _dynamicPerDay,
    Ticket[] _staticTickets,
    address[] _referrers,
    uint256[] _referralSplit,
    bytes32 _source
);

// Claim winnings + re-buy in one tx.
TicketAutoCompoundVault.depositAndCompound(
    uint256[] _ticketIds,
    address[] _referrers,
    uint256[] _referralSplit,
    bytes32 _source
);

// Claims.
Jackpot.claimWinnings(uint256[] _ticketIds);
Jackpot.claimReferralFees();
```

Confirm exact parameter types against the live ABI at [llms.megapot.io/abi](https://llms.megapot.io/abi) before you encode a call.

> [!NOTE]
>
> Before any purchase, approve USDC to the contract that receives payment (the contract you are calling). The full money-vs-telemetry split is covered in [Referrals & attribution](https://docs.megapot.io/developers/build/referrals-and-attribution.md).

***

## Key concepts

### Ticket struct

```solidity theme={null}
struct Ticket {
    uint8[] normals;  // 5 unique numbers in [1, ballMax]
    uint8 bonusball;  // 1 number in [1, bonusballMax]
}
```

`normals` is 5 unique numbers; ordering is not required to be sorted. Read `ballMax` and `bonusballMax` from `Jackpot.getDrawingState()` for the current drawing (**do not hardcode 30**), the ranges are per-drawing.

### DrawingState at a glance

`Jackpot.getDrawingState(_drawingId)` returns the full state of a drawing. The fields you will reach for most:

| Field | Meaning |
| - | - |
| `prizePool` | Total prize available for the drawing |
| `ticketPrice` | Cost per ticket, USDC (6 decimals) |
| `referralFee` | Fraction of ticket price paid to referrers (1e18 precision) |
| `referralWinShare` | Fraction of winnings shared with referrers (1e18 precision) |
| `globalTicketsBought` | Total tickets sold this drawing |
| `drawingTime` | Unix timestamp when the drawing executes |
| `ballMax` | Max normal-ball number for this drawing |
| `bonusballMax` | Max bonusball for this drawing |
| `jackpotLock` | `true` while a drawing is in progress |

Read the live referral rates from `referralFee` and `referralWinShare` rather than assuming a fixed percentage.

### Prize tiers

Matches map to one of 12 tiers, `0` through `11`, by the formula `matchedNormals * 2 + (bonusballMatch ? 1 : 0)`. Tier `0` is no match; tier `11` (all 5 normals + bonusball) is the jackpot.

| Tier | Normals matched | Bonusball |
| - | - | - |
| 0 | 0 | No |
| 1 | 0 | Yes |
| 2 | 1 | No |
| 3 | 1 | Yes |
| ... | ... | ... |
| 10 | 5 | No |
| 11 | 5 | Yes (jackpot) |

Tiers `0` and `2` never pay out.

**Reading what each tier pays.** Payout amounts are per-drawing, not protocol constants — the premium weights and guaranteed minimums behind them are owner-settable on `GuaranteedMinimumPayoutCalculator` and snapshotted when each drawing opens. Don't hardcode percentages. Two ways to read them:

| | Use |
| - | - |
| Active or settled round, in a UI | **Data API** — `Round.prize_tiers` on `GET /v1/rounds/active` or `/v1/rounds/{id}`. One call, no RPC. See [Pull data](https://docs.megapot.io/developers/pull-data.md#prize-tiers). |
| Straight from the chain, no API dependency | **RPC** — `getExpectedDrawingTierPayouts` for the drawing in flight, `getDrawingTierPayouts` for a settled one, `getDrawingTierInfo(drawingId)` for the weights and minimums in force |

Note that `getExpectedDrawingTierPayouts` ignores its arguments and returns the stored settled payouts once `_drawingId < currentDrawingId` — and all zeros during the rollover window before settlement writes them.

### Architecture

```mermaid theme={null}
flowchart TB
    subgraph Core["Core Contracts"]
        J[Jackpot]
        NFT[JackpotTicketNFT]
        LP[JackpotLPManager]
        PC[PayoutCalculator]
    end

    subgraph Helpers["User-Facing Helpers"]
        BF[BatchPurchase<br/>Facilitator]
        AS[AutoSubscription]
        ACV[AutoCompound<br/>Vault]
        BM[BridgeManager]
        RB[RandomTicketBuyer]
    end

    subgraph External["External"]
        SEP[ScaledEntropyProvider]
        PYTH[Pyth Network]
    end

    J --> NFT
    J --> LP
    J --> PC
    J --> SEP

    BF --> J
    AS --> J
    AS --> BF
    ACV --> J
    ACV --> NFT
    ACV --> BF
    BM --> J
    RB --> J

    SEP --> PYTH
```

***

## Which contract do I call?

**Jackpot** (`0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2`) is the main entry point. If you integrate only one contract, integrate this one. The rest are thin helpers that route into Jackpot, each for a specific job:

| Contract | Use it when you need to |
| - | - |
| **Jackpot** | Buy up to 10 custom-number tickets, claim winnings, claim referral fees, or deposit/withdraw as an LP |
| **JackpotRandomTicketBuyer** | Buy quick-pick tickets, with numbers chosen on-chain |
| **BatchPurchaseFacilitator** | Buy more than 10 tickets in a single drawing |
| **JackpotAutoSubscription** | Buy tickets automatically across multiple drawings |
| **TicketAutoCompoundVault** | Claim winnings and re-buy in one transaction |

***

## Security & audits

The Megapot protocol has been independently audited and operates autonomously: anyone can build on it without permission.

| Auditor | Date | Report |
| - | - | - |
| Zellic | Oct 2025 | [View report](https://github.com/coordinationlabs/megapot-v2-audit-reports/tree/main/zellic) |
| Code4rena | Nov 2025 | [View report](https://github.com/coordinationlabs/megapot-v2-audit-reports/blob/main/code4rena/) |
| Independent Auditors | Dec 2025 | [View report](https://github.com/coordinationlabs/megapot-v2-audit-reports/tree/main/ind-auditors) |

ABIs and contract artifacts are published at [github.com/coordinationlabs/megapot-v2-public](https://github.com/coordinationlabs/megapot-v2-public).

> [!WARNING]
>
> **The bug bounty program is no longer active.** New vulnerability submissions will not be addressed. See [Security](https://docs.megapot.io/appendix/security.md) and [Bug Bounty](https://docs.megapot.io/appendix/bug-bounty.md) for the closed program record. [Read Announcement](https://megapot.io/blog/thank-you-for-playing).

***

**Next:** [Back to Build](https://docs.megapot.io/developers/build) · [Referrals & attribution](https://docs.megapot.io/developers/build/referrals-and-attribution.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.