Build on the protocol

You are building something new. Not embedding a widget, not sharing a link, but a product of your own, on top of an open, permissionless jackpot protocol. Anyone can read its state, buy tickets, run draws, back the pot, and route referral fees, with no approval and no gatekeeper. potwars.xyz is one such build; yours is next. This page is the door to the deep reference. It is an orchestration map, not an ABI dump: four steps that take you from cold start to fluent, in roughly the order you will want them.

---

​

Step 1: Point your AI assistant at the skills

The fastest path to fluency is to let your coding assistant read the protocol’s own instructions. We publish a complete set of agent skills at llms.megapot.io: plain-markdown recipes with copy-paste viem and wagmi snippets, the current Base mainnet addresses, and the USDC-approval boilerplate every write needs. Add one line to your project’s instruction file:

For Megapot contract work, fetch https://llms.megapot.io

That works with:

• CLAUDE.md (Claude Code)
• AGENTS.md (Codex)
• .cursorrules (Cursor)
• .github/copilot-instructions.md (GitHub Copilot)
• Any other coding agent that reads a project-level instruction file

Your assistant loads the entry-point skill, a decision tree, the address table, the drawing lifecycle, and the standard USDC approve precondition, then deep-fetches the specific recipe for the task at hand (buy tickets, subscribe, claim winnings, claim referral fees, LP deposit/withdraw, auto-compound, read state, bootstrap a React app). Direct machine endpoints, if your tooling needs the raw artifacts: These are CDN-cached and CORS-open, so you can fetch them straight from a production frontend. When you show a contract signature in your own code or docs, confirm it against llms.megapot.io/abi/<Name>.txt, which is authoritative.

---

​

Step 2: Use the starter kit as a working reference

You rarely need to invent a flow. You need to see it wired correctly once. The Megapot Starter Kit (live at demo.megapot.io) is a five-page React + wagmi app where every core flow is already built: ticket purchase, claims, LP deposit and withdraw, subscriptions, and referral monetization. Two ways to use it:

• Fork it as the skeleton of your product and replace the UI.
• Just read it: open src/hooks/ for the contract-call wiring and src/pages/ for how each flow is composed. These are canonical patterns your assistant can copy and adapt.

After your assistant has the skills loaded (Step 1), point it at the kit for the implementation details:

Reference frontend at https://github.com/coordinationlabs/megapot-starter-kit: open src/hooks/ and src/pages/ for working implementations. Live demo: https://demo.megapot.io.

---

​

Step 3: Get attribution right from day one

This is the step most novel builds get wrong, and it is much cheaper to fix on day one than after launch. Read Referrals & Attribution before you write your first purchase call. The protocol keeps two concepts deliberately decoupled:

• Money: the _referrers (wallet addresses) and _referralSplit (weights that must sum to exactly 1e18) arguments. This is who actually gets paid: 10% of ticket fees plus a 10% win-share, split across up to 5 wallets. Read the live rates from Jackpot.getDrawingState().
• Telemetry: the trailing bytes32 _source argument. A bytes32 label for your app. It does not move money and is not returned by the Data API, but once allow-listed it shows your app’s name and icon on megapot.io results. See Get Listed.

Two consequences fall out of this design, and both are on you:

1. There is no on-chain self-referral guard. A wallet can list itself as a referrer. The protocol will not stop it. Your product’s attribution integrity is your responsibility.
2. _source and _referrers are independent. A label proves nothing about who got paid, and a payout carries no campaign label unless you set one. If your product needs to tie who referred to which channel to which account, you must bind account → source tag → wallet yourself at onboarding and carry it through every call.

A useful advanced pattern, illustrated in the starter kit’s referral flow, is the referrer chain: passing several referrer wallets with explicit splits (the multi-party _referrers / _referralSplit arrays) while tagging the same purchase with a _source label. That lets you compensate a chain of parties and attribute the conversion to a channel in one transaction, the money model and the telemetry model working side by side. Referrals & Attribution walks through it in full.

---

​

Step 4: Go deep

When you are ready to write contracts, the Protocol Reference is the single source of truth. It collects:

• The verified contract addresses on Base mainnet: Jackpot, JackpotTicketNFT, JackpotLPManager, the purchase helpers, and the payout calculator.
• The five purchase signatures: Jackpot.buyTickets, JackpotRandomTicketBuyer.buyTickets, BatchPurchaseFacilitator.createBatchOrder, JackpotAutoSubscription.createSubscription, and TicketAutoCompoundVault.depositAndCompound, each now carrying the trailing bytes32 _source argument.
• The modular architecture diagram: how the core contracts (Jackpot, NFT, LP, payout calculator) relate to the user-facing helpers and the Pyth-backed entropy provider.
• The independent security audits (Zellic, Code4rena, and independent auditors). The bug bounty program is closed; see Audits.

---

​

A minimal mental model

Before you dive in, the shape of a purchase is worth holding in your head:

1. Approve USDC to the contract that will receive payment (the Jackpot, or whichever helper you are calling). Tickets are never free: there is no zero-price primitive.
2. Build your Tickets: each is 5 unique normal numbers in [1, ballMax] plus 1 bonusball in [1, bonusballMax]. Read ballMax and bonusballMax from Jackpot.getDrawingState(); do not hardcode them.
3. Call the right method with _referrers, _referralSplit, and _source set per Step 3.
4. Claim later with Jackpot.claimWinnings(_ticketIds), and pull accrued referral fees with Jackpot.claimReferralFees().

Everything past this point (exact argument order, batch vs. subscription semantics, the entropy callback fee) lives in the Protocol Reference and at llms.megapot.io.

---

​

Where to next

• Start Here: the developer landing page and a map of every integration path.
• Referrals & Attribution: the money model, the telemetry model, and how to bind them correctly.
• Protocol Reference: addresses, the five purchase signatures, the architecture diagram, and audits.
• Add the jackpot to your site: if you do not need a fully custom build, the embeddable path is faster.
• Get Listed: get your app on the Ecosystem, Build, and results pages.

For dedicated integration support, DM @megapot on X or @pl on Warpcast.