> 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/referrals-and-attribution.md).

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

{% hint style="info" %}
**Just want a no-code share link that pays you?** See [Share a link & earn](/build-on-megapot/share-and-earn.md). For the earnings math (rates, levels, examples), see [Referral economics](/getting-started/how-to-refer/referral-economics-v2.md). For contract addresses and full signatures, see [Protocol reference](/build-on-megapot/build/protocol-reference.md).
{% endhint %}

***

## 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](/build-on-megapot/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
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.

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

***

## 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](/build-on-megapot/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
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.

***

## Setting referrers

### Single referrer (100%)

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

```typescript
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
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
const referrers = [];
const referralSplit = [];
```

{% hint style="warning" %}
`_referralSplit` must sum to **exactly** `1e18` (`1000000000000000000`). Anything else will revert. Empty arrays (`[]`, `[]`) are the only valid "no referrer" form.
{% endhint %}

***

## 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](/build-on-megapot/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
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](/build-on-megapot/build/claiming.md).

{% hint style="info" %}
**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](/getting-started/how-to-refer/referral-economics-v2.md) for the full breakdown.
{% endhint %}

***

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

{% hint style="info" %}
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](/build-on-megapot/share-and-earn.md). This page is for when you call the contracts yourself.
{% endhint %}

***

## See also

* [Referral economics](/getting-started/how-to-refer/referral-economics-v2.md), the earnings math: rates, levels, worked examples.
* [Share a link & earn](/build-on-megapot/share-and-earn.md): the no-code referral-link path.
* [Protocol reference](/build-on-megapot/build/protocol-reference.md): contract addresses, full method signatures, and ABIs.