# 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%).