> 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/build/protocol-reference.md).

# Protocol Reference

{% hint style="info" %}
**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).
{% endhint %}

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) |

{% hint style="warning" %}
`JackpotBridgeManager` and `ScaledEntropyProvider` are protocol internals: you do not call them directly and they are listed here by name only.
{% endhint %}

***

## Purchase signatures

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

```solidity
// 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.

{% hint style="info" %}
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](/build-on-megapot/build/referrals-and-attribution.md).
{% endhint %}

***

## Key concepts

### Ticket struct

```solidity
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) |

### Architecture

```mermaid
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).

{% hint style="info" %}
**Found a vulnerability?** Email <security@megapot.io>. Our [Security policy](/appendix/security.md) covers scope, what to include, our PGP key, and safe harbor.
{% endhint %}

***

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