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.
The protocol runs on Base mainnet (chain ID 8453). Everything you need to integrate (addresses, ABIs, and task recipes) is machine-readable and CORS-open, so your AI assistant can fetch it directly while it writes your code.
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:
https://llms.megapot.io/abi/<Name>.json
JSON ABI for a contract (e.g. Jackpot.json)
https://llms.megapot.io/abi/<Name>.txt
viem parseAbi strings (e.g. Jackpot.txt)
Machine-readable index of every URL on the site, for agents that crawl
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 andsrc/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: opensrc/hooks/andsrc/pages/for working implementations. Live demo:https://demo.megapot.io.
Want a complete project from a single paste? Ask your assistant (with the skills loaded) to bootstrap a fresh React + wagmi app. The react-setup skill scaffolds provider config and a working purchase component you can build on.
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 exactly1e18) 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 fromJackpot.getDrawingState().Telemetry: the trailing
bytes32 _sourceargument. A free-form channel or campaign label for your own analytics. It does not move money and is not returned by the Data API.
Two consequences fall out of this design, and both are on you:
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.
_sourceand_referrersare 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, andTicketAutoCompoundVault.depositAndCompound, each now carrying the trailingbytes32 _sourceargument.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) and how to report a vulnerability.
Pick the right tool for reads. Use RPC contract reads for live on-chain state (current jackpot size, a user's tickets, LP position) and for all writes. Use the Data API for read-only off-chain analytics: round history, wallet aggregates, leaderboards, anything cross-drawing. The bytes32 _source tag is not queryable through the Data API; keep your own telemetry store if you need to report on it.
A minimal mental model
Before you dive in, the shape of a purchase is worth holding in your head:
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.Build your
Tickets: each is 5 unique normal numbers in[1, ballMax]plus 1 bonusball in[1, bonusballMax]. ReadballMaxandbonusballMaxfromJackpot.getDrawingState(); do not hardcode them.Call the right method with
_referrers,_referralSplit, and_sourceset per Step 3.Claim later with
Jackpot.claimWinnings(_ticketIds), and pull accrued referral fees withJackpot.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.
For dedicated integration support, DM @megapot on X or @pl on Warpcast.
Last updated