> For the complete documentation index, see [llms.txt](https://docs.xyper.market/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyper.market/referral/marketing-referral-pool.md).

# marketing referral pool

The `MarketingReferralPool` is a separate reward pool for affiliates who refer participants (content creators) to Xyper. It operates independently from the project referral system and has stricter constraints to prevent abuse.

## Constraints

| Rule                 | Value                      |
| -------------------- | -------------------------- |
| Hold period          | 7 days from referral event |
| Rolling window       | 30 days                    |
| Cap per referral     | $10 USD                    |
| Cap per window       | $500 USD                   |
| Per-referral payment | One-time only              |

## How It Works

1. An affiliate shares their referral link
2. A new participant signs up using the link
3. A referral event is recorded with a unique `referralId` and timestamp
4. After 7 days, the affiliate can claim the reward via a signed voucher
5. The contract checks all caps before paying out

## USD Accounting

All amounts are tracked in USD with 8 decimal places (`E8`) to enable token-agnostic cap enforcement. The `marketingSigner` includes a price feed (`priceUsdE8`) in each voucher, and the contract uses it to compute the USD value of the payout and check against caps.

## Claiming

```http
POST /api/v1/me/referral/claim-intent/
```

Returns an EIP-712 voucher including:

* `referrer` — affiliate's wallet address
* `referralId` — unique event ID (replay protection)
* `tokenAddress` — payout token
* `amountRaw` — token amount
* `priceUsdE8` — token price at time of signing
* `deadline` — voucher expiry
* `unlockAt` — earliest claim time (7 days after referral)
* `windowStart` — 30-day window start

Submit the claim transaction to `MarketingReferralPool.claim(voucher, signature)`.

**Agent confirmation:**

```http
POST /api/agent/v1/me/referral/claim-confirm/
Body: { "txHash": "0x..." }
```

## Events

* `MarketingReferralClaimed(referrer, referralId, token, amountRaw, spentUsdE8)`