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

# 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](https://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.

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

***

## 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](https://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](https://llms.megapot.io), 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:

| Endpoint                                        | What it serves                                                                            |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `https://llms.megapot.io/abi/<Name>.json`       | JSON ABI for a contract (e.g. [`Jackpot.json`](https://llms.megapot.io/abi/Jackpot.json)) |
| `https://llms.megapot.io/abi/<Name>.txt`        | viem `parseAbi` strings (e.g. [`Jackpot.txt`](https://llms.megapot.io/abi/Jackpot.txt))   |
| [`/llms.txt`](https://llms.megapot.io/llms.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](https://github.com/coordinationlabs/megapot-starter-kit) (live at [demo.megapot.io](https://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`.

{% hint style="success" %}
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](https://llms.megapot.io/tasks/react-setup) scaffolds provider config and a working purchase component you can build on.
{% endhint %}

***

## 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](/build-on-megapot/build/referrals-and-attribution.md) 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 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:

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](/build-on-megapot/build/referrals-and-attribution.md) walks through it in full.

***

## Step 4: Go deep

When you are ready to write contracts, the [Protocol Reference](/build-on-megapot/build/protocol-reference.md) 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) and how to report a vulnerability.

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

***

## 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 `Ticket`s**: 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](/build-on-megapot/build/protocol-reference.md) and at [llms.megapot.io](https://llms.megapot.io).

***

## Where to next

* [**Start Here**](/build-on-megapot/start-here.md): the developer landing page and a map of every integration path.
* [**Referrals & Attribution**](/build-on-megapot/build/referrals-and-attribution.md): the money model, the telemetry model, and how to bind them correctly.
* [**Protocol Reference**](/build-on-megapot/build/protocol-reference.md): addresses, the five purchase signatures, the architecture diagram, and audits.
* [**Add the jackpot to your site**](/build-on-megapot/add-to-your-site.md): 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.