> ## Documentation Index
> Fetch the complete documentation index at: https://docs.megapot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

> [!NOTE]
>
> **Just want a no-code share link that pays you?** See [Share a link & earn](https://docs.megapot.io/developers/share-and-earn.md). For the earnings math (rates, levels, examples), see [Referral economics](https://docs.megapot.io/learn/referral-economics-v2.md). For contract addresses and full signatures, see [Protocol reference](https://docs.megapot.io/developers/build/protocol-reference.md).

***

## 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](https://docs.megapot.io/developers/share-and-earn.md), 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:

```typescript theme={null}
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.

> [!WARNING]
>
> **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](https://docs.megapot.io/developers/pull-data.md). Read it back yourself from on-chain events/logs if you want to use it.

Encode a short string into a `bytes32` with viem:

```typescript theme={null}
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.

> [!NOTE]
>
> **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](https://docs.megapot.io/developers/get-listed.md).

***

## Setting referrers

### Single referrer (100%)

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

```typescript theme={null}
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`:

```typescript theme={null}
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:

```typescript theme={null}
const referrers = [];
const referralSplit = [];
```

> [!WARNING]
>
> `_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](https://docs.megapot.io/developers/build/protocol-reference.md).)

| 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:

```typescript theme={null}
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](https://docs.megapot.io/developers/build/claiming.md).

> [!NOTE]
>
> **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](https://docs.megapot.io/learn/referral-economics-v2.md) 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` |

> [!NOTE]
>
> 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](https://docs.megapot.io/developers/share-and-earn.md). This page is for when you call the contracts yourself.

***

## See also

* [Referral economics](https://docs.megapot.io/learn/referral-economics-v2.md), the earnings math: rates, levels, worked examples.
* [Share a link & earn](https://docs.megapot.io/developers/share-and-earn.md): the no-code referral-link path.
* [Protocol reference](https://docs.megapot.io/developers/build/protocol-reference.md): contract addresses, full method signatures, and ABIs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.