# How to Earn by Referring

Integrate Megapot referrals into your application and earn fees from ticket purchases and winnings.

## How Referral Fees Work

Referrers earn from two sources:

| Fee Type         | When Earned                       | Description                |
| ---------------- | --------------------------------- | -------------------------- |
| **Purchase Fee** | When referred user buys tickets   | Percentage of ticket price |
| **Win Share**    | When referred user claims a prize | Percentage of winnings     |

Both fee percentages are set at the protocol level and can be read from the drawing state:

* `referralFee` - fraction of ticket price paid to referrers
* `referralWinShare` - fraction of claimed winnings paid to referrers

Fees accumulate in the Jackpot contract and can be claimed at any time.

***

## Setting a Referrer

When purchasing tickets through any method (`Jackpot.buyTickets`, `BatchPurchaseFacilitator`, or `JackpotAutoSubscription`), you pass referrer information in two arrays:

| Parameter        | Type        | Description                                 |
| ---------------- | ----------- | ------------------------------------------- |
| `_referrers`     | `address[]` | Array of referrer wallet addresses          |
| `_referralSplit` | `uint256[]` | Weight for each referrer (must sum to 1e18) |

### Single Referrer

For a single referrer receiving 100% of fees:

```
_referrers: ["0xYourReferrerAddress"]
_referralSplit: [1000000000000000000]  // 1e18 = 100%
```

**Example with `Jackpot.buyTickets`:**

```
jackpot.buyTickets(
    tickets,                              // ticket array
    recipientAddress,                     // who receives the NFTs
    ["0xYourReferrerAddress"],            // single referrer
    [1000000000000000000],                // 100% to this referrer
    "your-app-name"                       // source identifier
);
```

### Multiple Referrers

Split fees between multiple addresses by providing matching arrays:

**50/50 split between two referrers:**

```
_referrers: ["0xReferrer1", "0xReferrer2"]
_referralSplit: [500000000000000000, 500000000000000000]  // 0.5e18 each
```

**80/20 split (e.g., primary affiliate and sub-affiliate):**

```
_referrers: ["0xPrimaryReferrer", "0xSubAffiliate"]
_referralSplit: [800000000000000000, 200000000000000000]  // 0.8e18 + 0.2e18
```

**Three-way split (70/20/10):**

```
_referrers: ["0xReferrer1", "0xReferrer2", "0xReferrer3"]
_referralSplit: [700000000000000000, 200000000000000000, 100000000000000000]
```

The split weights must sum to exactly `1e18` (1000000000000000000).

### No Referrer

Pass empty arrays if there's no referrer:

```
_referrers: []
_referralSplit: []
```

***

## Referral Scheme Tracking

Each unique combination of referrers and splits creates a "referral scheme" that is stored with the ticket. This scheme is used to:

1. Pay purchase fees immediately when tickets are bought
2. Pay win share fees when those tickets win prizes

You can look up a scheme's details using:

```solidity
ReferralScheme memory scheme = jackpot.getReferralScheme(schemeId);
// scheme.referrers - array of referrer addresses
// scheme.referralSplit - array of split weights
```

***

## Viewing Accumulated Fees

Check your claimable referral balance using the `referralFees` mapping:

```solidity
uint256 claimableAmount = jackpot.referralFees(yourAddress);
```

This returns the total USDC (6 decimals) you can claim. The balance includes:

* Purchase fees from all tickets bought with you as referrer
* Win share fees from any claimed winnings by users you referred

***

## Claiming Fees

Call `claimReferralFees()` to withdraw your accumulated fees:

```solidity
jackpot.claimReferralFees();
```

This transfers your entire claimable balance to your wallet. There is no minimum claim amount.

***

## Reading Fee Parameters

Get the current referral fee rates from the drawing state:

```solidity
uint256 drawingId = jackpot.currentDrawingId();
IJackpot.DrawingState memory state = jackpot.getDrawingState(drawingId);

uint256 purchaseFeeRate = state.referralFee;      // e.g., 0.05e18 = 5%
uint256 winShareRate = state.referralWinShare;    // e.g., 0.10e18 = 10%
```

These values use 1e18 precision (1e18 = 100%).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.megapot.io/developers/refer-to-earn.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.