Gift Tickets & Run Giveaways

Reward your users with jackpot tickets: a thank-you, a referral incentive, a contest prize, or a community drop. The recipient gets real ticket NFTs in their own wallet and can win and claim like any other player.

Tickets are never free, you fund every gift. There is no zero-price primitive (setting a ticket price to 0 reverts). When you gift a ticket, you pay for it in USDC. The recipient pays nothing.

There are two ways to do this: a no-code path on megapot.io for one-off or small giveaways, and an in-code path for programmatic rewards inside your own app.

---

No code: gift from megapot.io

The fastest way to gift, with nothing to build:

1. Go to megapot.io/gift.

2. Enter the recipient's wallet address.

3. Choose how many tickets to buy and confirm: you pay the USDC.

The recipient receives the ticket NFTs directly in their wallet. Best for one-off rewards or small, hand-picked giveaways where you don't need to wire anything into your product.

---

In code: gift via the recipient param

Every purchase call takes a _recipient argument. To gift, set _recipient to your user's wallet while you remain the buyer and payer. You approve and spend the USDC, the tickets are minted to them.

Optionally, set _referrers to your own wallet so you also earn referral fees on the gifts you fund (10% of the ticket fee, plus 10% win-share if those tickets win). See Referrals & attribution for the referrer arrays in detail.

Here is the minimal flow with Jackpot.buyTickets: approve USDC to the Jackpot contract, then buy tickets for your user:

import { stringToHex } from "viem";

const JACKPOT = "0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2";

// Your user's wallet: the gift recipient (synthetic example)
const userWallet = "0x1111111111111111111111111111111111111111";
// Your wallet: earns referral fees on the gift (optional)
const yourWallet = "0x2222222222222222222222222222222222222222";

// 1. Read the live ticket price and ball ranges
const drawingId = await jackpot.currentDrawingId();
const state = await jackpot.getDrawingState(drawingId);
const ticketPrice = state.ticketPrice; // USDC, 6 decimals

// 2. Define the tickets you're gifting.
//    5 unique normals in [1, state.ballMax]; bonusball in [1, state.bonusballMax].
//    Do NOT hardcode the ranges: read ballMax / bonusballMax from getDrawingState().
const tickets = [{ normals: [7, 14, 21, 28, 30], bonusball: 12 }];

// 3. Approve USDC to the Jackpot contract (the contract that receives payment)
const totalCost = ticketPrice * BigInt(tickets.length);
await usdc.approve(JACKPOT, totalCost);

// 4. Buy: recipient is your user; referrer (optional) is you
const tx = await jackpot.buyTickets(
    tickets,
    userWallet,                       // _recipient: your user
    [yourWallet],                     // _referrers: you (or [] to skip)
    [1000000000000000000n],           // _referralSplit: 100% (1e18), or []
    stringToHex("my-giveaway", { size: 32 }) // _source: your analytics label
);
await tx.wait();
// Tickets are minted directly to userWallet

The trailing _source is a free-form bytes32 label for your own analytics. It does not affect payments. If you skip the referrer, pass empty arrays ([], []) for _referrers and _referralSplit.

Gifting more than 10, or recurring drops

Other purchase methods take a _recipient too, so you can gift at scale or on a schedule:

• BatchPurchaseFacilitator.createBatchOrder: gift more than 10 tickets in one drawing.

• JackpotAutoSubscription.createSubscription: drip gifted tickets across multiple drawings (e.g. a daily reward).

• JackpotRandomTicketBuyer.buyTickets: gift quick-pick tickets with numbers chosen on-chain.

For the full method menu and which one to pick, see add-to-your-site.md. For exact addresses and signatures, see build/protocol-reference.md.

---

What your users experience (and KYC)

Recipients receive standard ticket NFTs and can claim any winnings into their wallet without KYC; cashing out / transferring out of that wallet requires KYC.

---

Track what you gave out

Because the buyer is you and the recipient is your user, query the gift from the recipient's side using the Data API wallet endpoints:

GET /v1/wallets/{recipient}/tickets

This returns the tickets now held by that wallet, including the ones you gifted. Pair it with GET /v1/wallets/{recipient}/wins to see if a gift paid off. See pull-data.md for auth, pagination, and the rest of the wallet endpoints.

The _source label you set on a gift is not queryable through the Data API. Keep your own record if you need to attribute gifts to a specific campaign.

---

Running a larger campaign

The patterns above cover one-off gifts and programmatic rewards you fund directly. Large, self-serve free-ticket campaigns (for example claim links your community redeems themselves) are team-provisioned today, not self-serve. Contact the team to set one up.