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

# Referral System

> Manage referral codes and track referral rewards

## Description

The referral API endpoints allow you to generate referral codes, track referral performance, and view reward statistics. Users earn points when their referrals trade, create tokens, or achieve milestones.

## Endpoints

### Get Referral Code

<ParamField path="GET /api/referral/code" type="endpoint">
  Generate or retrieve your unique referral code
</ParamField>

#### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token or wallet signature for authentication
</ParamField>

#### Response

```json theme={null}
{
  "code": "INKY-ABC123",
  "created_at": "2024-01-15T10:30:00Z",
  "total_referrals": 15,
  "active_referrals": 12,
  "total_points_earned": 5250.5
}
```

***

### Get Referral Stats

<ParamField path="GET /api/referral/stats" type="endpoint">
  Get detailed statistics about your referral performance
</ParamField>

#### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token or wallet signature for authentication
</ParamField>

#### Query Parameters

<ParamField query="period" type="string" default="all">
  Time period for stats. Options: `24h`, `7d`, `30d`, `all`
</ParamField>

#### Response

```json theme={null}
{
  "referral_code": "INKY-ABC123",
  "stats": {
    "total_referrals": 15,
    "active_referrals": 12,
    "total_points_earned": 5250.5,
    "points_from_trading": 3500.2,
    "points_from_token_creation": 1000.0,
    "points_from_milestones": 750.3
  },
  "recent_activity": [
    {
      "type": "trade",
      "referral_address": "0xabc...def",
      "points_earned": 25.5,
      "timestamp": "2024-01-15T09:00:00Z"
    }
  ],
  "top_referrals": [
    {
      "address": "0x123...456",
      "points_generated": 850.2,
      "joined_at": "2024-01-10T08:00:00Z"
    }
  ]
}
```

***

### Register with Referral Code

<ParamField path="POST /api/referral/register" type="endpoint">
  Register a new user with a referral code
</ParamField>

#### Request Body

<ParamField body="referral_code" type="string" required>
  The referral code to use for registration
</ParamField>

<ParamField body="wallet_address" type="string" required>
  The wallet address of the new user
</ParamField>

#### Response

```json theme={null}
{
  "success": true,
  "message": "Successfully registered with referral code",
  "referrer": "0xabc...def"
}
```

***

### Get Referral Leaderboard

<ParamField path="GET /api/referral/leaderboard" type="endpoint">
  View the top referrers on the platform
</ParamField>

#### Query Parameters

<ParamField query="limit" type="number" default="10">
  Number of top referrers to return (max: 100)
</ParamField>

<ParamField query="period" type="string" default="all">
  Time period for leaderboard. Options: `24h`, `7d`, `30d`, `all`
</ParamField>

#### Response

```json theme={null}
{
  "leaderboard": [
    {
      "rank": 1,
      "address": "0xabc...def",
      "referral_code": "INKY-TOP1",
      "total_referrals": 523,
      "points_earned": 125000.5
    },
    {
      "rank": 2,
      "address": "0x123...456",
      "referral_code": "INKY-MOON",
      "total_referrals": 412,
      "points_earned": 98500.3
    }
  ],
  "updated_at": "2024-01-15T10:00:00Z"
}
```

## Reward Structure

| Action                    | Reward        | Description                                        |
| ------------------------- | ------------- | -------------------------------------------------- |
| **Buy Volume**            | 10% of points | Earn 10% of points from referral's ETH buy volume  |
| **Sell Volume**           | 10% of points | Earn 10% of points from referral's ETH sell volume |
| **Token Creation**        | 10% bonus     | 10% bonus when referral creates a new token        |
| **Milestone Achievement** | Variable      | Points when referral hits certain milestones       |

## Rate Limiting

Referral API endpoints have specific rate limits:

* Generate/Get Code: 10 requests per minute
* Stats/Leaderboard: 30 requests per minute
* Registration: 5 requests per minute per IP

<RequestExample>
  ```bash cURL theme={null}
  # Get your referral code
  curl -X GET "https://inkypump.com/api/referral/code" \
    -H "Authorization: Bearer YOUR_TOKEN"

  # Get referral statistics
  curl -X GET "https://inkypump.com/api/referral/stats?period=7d" \
    -H "Authorization: Bearer YOUR_TOKEN"

  # Register with referral code
  curl -X POST "https://inkypump.com/api/referral/register" \
    -H "Content-Type: application/json" \
    -d '{
      "referral_code": "INKY-ABC123",
      "wallet_address": "0xnewuser..."
    }'

  # Get leaderboard
  curl -X GET "https://inkypump.com/api/referral/leaderboard?limit=20&period=30d"
  ```

  ```typescript TypeScript theme={null}
  // Get your referral code
  const codeResponse = await fetch('https://inkypump.com/api/referral/code', {
    headers: {
      'Authorization': `Bearer ${authToken}`
    }
  });
  const codeData = await codeResponse.json();

  // Get referral statistics
  const statsResponse = await fetch('https://inkypump.com/api/referral/stats?period=7d', {
    headers: {
      'Authorization': `Bearer ${authToken}`
    }
  });
  const statsData = await statsResponse.json();

  // Register with referral code
  const registerResponse = await fetch('https://inkypump.com/api/referral/register', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      referral_code: 'INKY-ABC123',
      wallet_address: '0xnewuser...'
    })
  });
  const registerData = await registerResponse.json();

  // Get leaderboard
  const leaderboardResponse = await fetch('https://inkypump.com/api/referral/leaderboard?limit=20&period=30d');
  const leaderboardData = await leaderboardResponse.json();
  ```

  ```python Python theme={null}
  import requests

  # Get your referral code
  code_response = requests.get(
      "https://inkypump.com/api/referral/code",
      headers={"Authorization": f"Bearer {auth_token}"}
  )
  code_data = code_response.json()

  # Get referral statistics
  stats_response = requests.get(
      "https://inkypump.com/api/referral/stats",
      params={"period": "7d"},
      headers={"Authorization": f"Bearer {auth_token}"}
  )
  stats_data = stats_response.json()

  # Register with referral code
  register_response = requests.post(
      "https://inkypump.com/api/referral/register",
      json={
          "referral_code": "INKY-ABC123",
          "wallet_address": "0xnewuser..."
      }
  )
  register_data = register_response.json()

  # Get leaderboard
  leaderboard_response = requests.get(
      "https://inkypump.com/api/referral/leaderboard",
      params={"limit": 20, "period": "30d"}
  )
  leaderboard_data = leaderboard_response.json()
  ```
</RequestExample>