Add Megapot to Your Site

This guide covers the different ways to purchase Megapot tickets programmatically. Choose the right method based on your use case.

Quick Reference

For dApp based execution:

Scenario	Contract	Execution	Ticket Types
<=10 tickets, single drawing	Jackpot	Immediate	Static only
>10 tickets, single drawing	BatchPurchaseFacilitator	Keeper-executed	Static + Dynamic
Multiple drawings	JackpotAutoSubscription	Keeper-executed	Static + Dynamic

For execution from a smart contract

Scenario	Contract	Execution	Ticket Types
<=10 tickets, pre-defined tickets	Jackpot	Immediate	Static only
<=10 tickets, random tickets	JackpotRandomTicketBuyer	Immediate	Dynamic only
>10 tickets, single drawing	BatchPurchaseFacilitator	Keeper-executed	Static + Dynamic
Multiple drawings	JackpotAutoSubscription	Keeper-executed	Static + Dynamic

Key Concepts

Static vs Dynamic Tickets

Static tickets are user-defined number combinations. The client specifies exactly which 5 normal numbers and bonusball to play.

Dynamic tickets are randomly generated on-chain. The contract generates valid random numbers at execution time.

Recommended Limits

When using BatchPurchaseFacilitator or JackpotAutoSubscription:

• Limit static tickets to 100 per order

• If purchasing more than 100 tickets, make the rest dynamic

This recommendation exists for gas efficiency and storage optimization. Static tickets must be stored on-chain and validated individually, while dynamic tickets are generated on-the-fly during execution.

Ticket Structure

All methods use the same ticket format:

Ticket {
    uint8[] normals   // 5 unique numbers in [1, normalBallMax]
    uint8 bonusball   // 1 number in [1, bonusballMax]
}

The current normalBallMax is 30. The bonusballMax varies by drawing and can be read from the drawing state. You can check the Jackpot contract for the most up to date normalBallMax and bonusballMax by calling Jackpot.getDrawingState(currentDrawingId).

---

Direct Purchase: Jackpot.buyTickets

When to use: Single-drawing purchases of less than or equal to 10 tickets where you want full control over number selection (on or off-chain) or are fine generating random tickets in the client.

This is the most direct method. Your client generates the ticket numbers, and tickets are minted immediately in the same transaction.

Interface

function buyTickets(
    Ticket[] memory _tickets,
    address _recipient,
    address[] memory _referrers,
    uint256[] memory _referralSplit,
    bytes32 _source
) external returns (uint256[] memory ticketIds)

Parameters

Parameter	Type	Description
_tickets	Ticket[]	Array of tickets to purchase. Each ticket has normals (5 unique numbers 1-30) and bonusball (1 number within drawing's bonusball range)
_recipient	address	Address that will own the ticket NFTs
_referrers	address[]	Referrer addresses for fee sharing. Pass empty array [] if none
_referralSplit	uint256[]	Weight for each referrer, scaled to 1e18. Must sum to 1e18 if provided. Pass empty array [] if no referrers
_source	bytes32	Identifier for your application (used for analytics). e.g., bytes32("my-app")

Example Parameters

2 tickets with no referrer:

_tickets: [
    { normals: [7, 14, 21, 28, 30], bonusball: 12 },
    { normals: [3, 11, 19, 27, 29], bonusball: 8 }
]
_recipient: "0xYourUserAddress"
_referrers: []
_referralSplit: []
_source: "my-app"

To learn how you can earn referrer fees and a portion of your referrals winnings visit our [How to Earn by Referring](refer-to-earn.md) guide which will show you how to properly parameterize the `_referrers` and `_referralSplit` arrays, plus claim any accrued referral fees!

Prerequisites

1. Read the current ticket price from the drawing state

2. Approve USDC spending: usdc.approve(jackpotAddress, ticketPrice * ticketCount)

3. Ensure ticket numbers are valid (normals in range, unique, sorted; bonusball in range)

---

Batch Purchase: BatchPurchaseFacilitator

When to use: Single-drawing purchases of more than 10 tickets.

Batch orders are prepaid and executed by keepers in chunks. This is more gas-efficient for large orders and supports a mix of static (user-defined) and dynamic (random) tickets.

Interface

function createBatchOrder(
    address _recipient,
    uint64 _dynamicTicketCount,
    IJackpot.Ticket[] calldata _userStaticTickets,
    address[] calldata _referrers,
    uint256[] calldata _referralSplit
) external

Parameters

Parameter	Type	Description
_recipient	address	Address that will own the ticket NFTs
_dynamicTicketCount	uint64	Number of random tickets to generate
_userStaticTickets	Ticket[]	User-defined tickets (max 100 recommended)
_referrers	address[]	Referrer addresses for fee sharing
_referralSplit	uint256[]	Weight for each referrer, scaled to 1e18

Example Parameters

50 tickets: 40 dynamic + 10 static, no referrer:

_recipient: "0xUserAddress"
_dynamicTicketCount: 40
_userStaticTickets: [
    { normals: [1, 2, 3, 4, 5], bonusball: 1 },
    { normals: [6, 7, 8, 9, 10], bonusball: 2 },
    { normals: [11, 12, 13, 14, 15], bonusball: 3 },
    { normals: [16, 17, 18, 19, 20], bonusball: 4 },
    { normals: [21, 22, 23, 24, 25], bonusball: 5 },
    { normals: [26, 27, 28, 29, 30], bonusball: 6 },
    { normals: [5, 10, 15, 20, 25], bonusball: 7 },
    { normals: [1, 8, 15, 22, 29], bonusball: 8 },
    { normals: [2, 9, 16, 23, 30], bonusball: 9 },
    { normals: [3, 10, 17, 24, 28], bonusball: 10 }
]
_referrers: []
_referralSplit: []

500 tickets, all dynamic:

_recipient: "0xUserAddress"
_dynamicTicketCount: 500
_userStaticTickets: []
_referrers: []
_referralSplit: []

To learn how you can earn referrer fees and a portion of your referrals winnings visit our [How to Earn by Referring](refer-to-earn.md) guide which will show you how to properly parameterize the `_referrers` and `_referralSplit` arrays, plus claim any accrued referral fees!

Prerequisites

1. Read the current ticket price

2. Calculate total cost: ticketPrice * (dynamicTicketCount + staticTickets.length)

3. Approve USDC spending on the BatchPurchaseFacilitator address

4. Ensure no existing active batch order for this recipient

Execution Flow

1. You call createBatchOrder, USDC is transferred, order is queued

2. Protocol keepers call executeBatchOrder to process tickets in batches

3. Large orders may take multiple blocks to complete

4. Tickets are minted to the recipient as they're processed

Cancellation

Call cancelBatchOrder() to cancel and receive a refund for unexecuted tickets. Orders are also auto-cancelled and refunded to the ticket recipient address if:

• The drawing locks before execution completes

• The order was created for a previous drawing

---

Recurring Purchase: JackpotAutoSubscription

When to use: Purchases that span multiple drawings, regardless of ticket count per day.

Subscriptions let users prepay for tickets across many drawings. The same static tickets play every drawing, combined with fresh dynamic tickets.

Interface

function createSubscription(
    address _recipient,
    uint64 _totalDays,
    uint64 _dynamicTicketCount,
    IJackpot.Ticket[] calldata _userStaticTickets,
    address[] calldata _referrers,
    uint256[] calldata _referralSplit
) external

Parameters

Parameter	Type	Description
_recipient	address	Address that will own the ticket NFTs each drawing
_totalDays	uint64	Number of drawings to participate in
_dynamicTicketCount	uint64	Random tickets to purchase per drawing
_userStaticTickets	Ticket[]	User-defined tickets to play every drawing (max 100 recommended)
_referrers	address[]	Referrer addresses for all purchases
_referralSplit	uint256[]	Weight for each referrer, scaled to 1e18

Example Parameters

30 days, 5 dynamic tickets per day, no static tickets:

_recipient: "0xUserAddress"
_totalDays: 30
_dynamicTicketCount: 5
_userStaticTickets: []
_referrers: []
_referralSplit: []

// Total tickets: 30 x 5 = 150
// Total cost: 150 x ticketPrice

7 days, 3 dynamic + 2 lucky numbers per day:

_recipient: "0xUserAddress"
_totalDays: 7
_dynamicTicketCount: 3
_userStaticTickets: [
    { normals: [7, 14, 21, 28, 30], bonusball: 7 },
    { normals: [4, 8, 15, 16, 23], bonusball: 12 }
]
_referrers: []
_referralSplit: []

// Total tickets per day: 3 + 2 = 5
// Total tickets: 7 x 5 = 35
// Total cost: 35 x ticketPrice

To learn how you can earn referrer fees and a portion of your referrals winnings visit our [How to Earn by Referring](refer-to-earn.md) guide which will show you how to properly parameterize the `_referrers` and `_referralSplit` arrays, plus claim any accrued referral fees!

Prerequisites

1. Read the current ticket price (this price is locked for the subscription duration)

2. Calculate total cost: ticketPrice * totalDays * (dynamicTicketCount + staticTickets.length)

3. Approve USDC spending on the JackpotAutoSubscription address

4. Ensure no existing active subscription for this recipient

Price Protection

The ticket price is locked when you create the subscription. If the protocol increases ticket prices, your subscription is automatically cancelled and remaining funds are refunded to the ticket recipient address. This protects users from unexpected cost increases.

Cancellation

Call cancelSubscription() to cancel and receive a refund for remaining days. The subscription also auto-cancels if:

• Ticket price changes from the subscribed price

• Referrer configuration becomes invalid

Integration with Batch Facilitator

For subscriptions with large daily ticket counts, the AutoSubscription contract automatically routes execution through the BatchPurchaseFacilitator for efficiency.

---

Random Tickets: JackpotRandomTicketBuyer

When to use:

• On-chain integrations that don't want to implement random ticket generation

• Quick purchases where the user doesn't care about specific numbers

• Any scenario where you want random numbers without client-side generation

This helper contract generates random tickets using on-chain entropy (prevrandao, block hash, nonce) and calls Jackpot.buyTickets directly. Tickets are minted immediately.

Interface

function buyTickets(
    uint256 _count,
    address _recipient,
    address[] memory _referrers,
    uint256[] memory _referralSplitBps,
    bytes32 _source
) external returns (uint256[] memory ticketIds)

Parameters

Parameter	Type	Description
_count	uint256	Number of random tickets to generate and purchase
_recipient	address	Address that will own the ticket NFTs
_referrers	address[]	Referrer addresses for fee sharing. Pass empty array if none
_referralSplitBps	uint256[]	Weight for each referrer, scaled to 1e18. Must sum to 1e18 if provided
_source	bytes32	Identifier for your application

Example Parameters

5 random tickets, no referrer:

_count: 5
_recipient: "0xUserAddress"
_referrers: []
_referralSplitBps: []
_source: "quick-play"

To learn how you can earn referrer fees and a portion of your referrals winnings visit our [How to Earn by Referring](refer-to-earn.md) guide which will show you how to properly parameterize the `_referrers` and `_referralSplit` arrays, plus claim any accrued referral fees!

Prerequisites

1. Read the current ticket price from the Jackpot contract

2. Approve USDC spending on the JackpotRandomTicketBuyer address: usdc.approve(randomBuyerAddress, ticketPrice * count)

Note on Randomness

The on-chain randomness used for ticket generation is sufficient for creating unpredictable ticket numbers, but it is not the same as the cryptographically secure Pyth Network entropy used for drawing winners. The drawing itself remains provably fair.

---

Common Patterns

Calculating Total Cost

totalCost = ticketPrice x ticketCount

Read ticketPrice from:

uint256 drawingId = jackpot.currentDrawingId();
uint256 ticketPrice = jackpot.getDrawingState(drawingId).ticketPrice;

USDC Approval

Always approve the correct contract address:

Method	Approve USDC to
Jackpot.buyTickets	Jackpot contract
JackpotRandomTicketBuyer.buyTickets	JackpotRandomTicketBuyer contract
BatchPurchaseFacilitator.createBatchOrder	BatchPurchaseFacilitator contract
JackpotAutoSubscription.createSubscription	JackpotAutoSubscription contract