Referrals & Attribution

This is the canonical reference for how referral money and attribution work on Megapot’s on-chain protocol (Base mainnet, chain 8453). The most important thing to understand up front: referral money and attribution are two independent, decoupled concepts. One pays people. The other labels traffic. They live in separate parameters, and one never affects the other.

Concept	Parameter(s)	What it does	Affects payments?	In the Data API?
Money	`_referrers` + `_referralSplit`	Pays wallet addresses a cut of ticket fees and winnings	Yes	No
Telemetry	`_source` (`bytes32`)	A free-form channel/campaign label for your analytics	No	No

Just want a no-code share link that pays you? See Share a link & earn. For the earnings math (rates, levels, examples), see Referral economics. For contract addresses and full signatures, see Protocol reference.

1. Money: `_referrers` and `_referralSplit`

This is who gets paid. Two parallel arrays travel with the purchase:

Parameter	Type	Description
`_referrers`	`address[]`	Wallet addresses that receive the referral cut. Up to 5 referrers.
`_referralSplit`	`uint256[]`	Weight for each referrer, at `1e18` precision. Must sum to exactly `1e18`.

The two arrays are positional and must be the same length: _referralSplit[i] is the weight for _referrers[i]. When you pass your own referrer scheme in a contract call, referrers earn from two sources:

Source	When	Amount
Ticket fee	When a referred user buys tickets	10% of the ticket price
Win-share	When a referred user claims winnings	10% of the winnings

(Referrals made by simply sharing a megapot.io link, with no contract call, earn 8% and 8% instead.) These rates are set at the protocol level. Read the live values from Jackpot.getDrawingState() rather than hardcoding them:

const drawingId = await jackpot.currentDrawingId();
const state = await jackpot.getDrawingState(drawingId);

const referralFee = state.referralFee;           // ticket-fee rate, 1e18 = 100%
const referralWinShare = state.referralWinShare;  // win-share rate, 1e18 = 100%

Both fields use 1e18 precision (1e18 = 100%). Read them live rather than assuming a fixed rate.

There is no on-chain self-referral guard. A wallet may list itself (or any address) as a referrer. The protocol does not police who you attribute purchases to. Attribution integrity is the integrator’s responsibility.

2. Telemetry: `_source` (`bytes32`)

_source is a free-form label you attach to a purchase for your own analytics: a channel, campaign, or surface tag. It does not move any money, has nothing to do with _referrers, and is not returned by the Data API. Read it back yourself from on-chain events/logs if you want to use it. Encode a short string into a bytes32 with viem:

import { stringToHex } from "viem";

const source = stringToHex("mysite", { size: 32 });
// pass `source` as the trailing _source argument

Pass bytes32(0) (an all-zero value) when you have nothing to tag.

Want your app to show up on megapot.io? Use one tag for your app on every purchase call and send it to the team to be allow-listed. Allow-listed tags show your app’s name and icon on tickets and drawing results. See Get Listed.

Setting referrers

Single referrer (100%)

One wallet receives the entire referral cut. The single weight is 1e18:

const referrers = ["0x1111111111111111111111111111111111111111"];
const referralSplit = [1000000000000000000n]; // 1e18 = 100%

Split across multiple referrers (70/20/10)

Provide matching arrays. The weights must sum to exactly 1e18:

const referrers = [
  "0x1111111111111111111111111111111111111111", // 70%
  "0x2222222222222222222222222222222222222222", // 20%
  "0x1111111111111111111111111111111111111111", // 10% (any address; example reuse)
];
const referralSplit = [
  700000000000000000n,  // 0.70e18
  200000000000000000n,  // 0.20e18
  100000000000000000n,  // 0.10e18
];
// 0.70e18 + 0.20e18 + 0.10e18 = 1e18 ✅

No referrer

Pass two empty arrays:

const referrers = [];
const referralSplit = [];

_referralSplit must sum to exactly 1e18 (1000000000000000000). Anything else will revert. Empty arrays ([], []) are the only valid “no referrer” form.

Which calls carry referrers

Five purchase methods accept _referrers and _referralSplit. All five also take the trailing bytes32 _source telemetry tag. (For full argument lists and the contract addresses to call, see Protocol reference.)

Method	Use case
`Jackpot.buyTickets(..., _referrers, _referralSplit, _source)`	Up to 10 custom-number tickets, minted immediately
`JackpotRandomTicketBuyer.buyTickets(..., _referrers, _referralSplit, _source)`	Random / quick-pick, minted immediately
`BatchPurchaseFacilitator.createBatchOrder(..., _referrers, _referralSplit, _source)`	More than 10 tickets, keeper-executed
`JackpotAutoSubscription.createSubscription(..., _referrers, _referralSplit, _source)`	Recurring across drawings, keeper-executed
`TicketAutoCompoundVault.depositAndCompound(..., _referrers, _referralSplit, _source)`	Claim winnings + re-buy in one transaction

The referrer arrays and source occupy the same trailing positions on every method, so the same (referrers, referralSplit, source) triple drops into any of them. Example, earning fees on a direct purchase:

const tx = await jackpot.buyTickets(
  tickets,           // Ticket[]
  recipientAddress,  // who receives the NFTs
  ["0x1111111111111111111111111111111111111111"], // _referrers (you)
  [1000000000000000000n],                          // _referralSplit (100%)
  stringToHex("mysite", { size: 32 }),             // _source (telemetry)
);

Claiming your referral fees

Your referral earnings accrue as a claimable USDC balance inside the Jackpot contract, combining ticket fees and win-share from users you referred. Withdraw them any time with Jackpot.claimReferralFees(). For the read-balance and withdraw calls, see Claim winnings & fees.

Two referral levels. Referring someone who then refers others earns you a smaller secondary share on that downstream activity, on top of your direct referral earnings. See Referral economics for the full breakdown.

The off-chain bridge: codes vs. wallets

The hosted megapot.io product issues each user a 6-character referral code and a share link of the form https://megapot.io/r/{CODE} (for example https://megapot.io/r/7H4K2Q). That code is a megapot.io convenience, not an on-chain concept. Behind the scenes it resolves to a referrer wallet address, and that wallet is what actually gets passed into _referrers when a purchase is made through the hosted app. When you build your own flow, skip the code entirely: pass the referrer wallet address directly in _referrers. There is no code-to-wallet resolution step on-chain: the contracts only ever see wallet addresses.

Context	What identifies the referrer
megapot.io hosted product	A `/r/{CODE}` link (code resolves to a wallet off-chain)
Your own integration	The referrer wallet address, passed straight into `_referrers`

If you only want the no-code path (a share link that pays your wallet without writing any contract calls), that’s Share a link & earn. This page is for when you call the contracts yourself.

Getting Started

Learn

Build on Megapot

Appendix

Legal

Referrals & Attribution

1. Money: `_referrers` and `_referralSplit`

2. Telemetry: `_source` (`bytes32`)

Setting referrers

Single referrer (100%)

Split across multiple referrers (70/20/10)

No referrer

Which calls carry referrers

Claiming your referral fees

The off-chain bridge: codes vs. wallets

See also

​1. Money: _referrers and _referralSplit

​2. Telemetry: _source (bytes32)

​Setting referrers

​Single referrer (100%)

​Split across multiple referrers (70/20/10)

​No referrer

​Which calls carry referrers

​Claiming your referral fees

​The off-chain bridge: codes vs. wallets

​See also

1. Money: `_referrers` and `_referralSplit`

2. Telemetry: `_source` (`bytes32`)

Setting referrers

Single referrer (100%)

Split across multiple referrers (70/20/10)

No referrer

Which calls carry referrers

Claiming your referral fees

The off-chain bridge: codes vs. wallets

See also