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

GET /api/referral/code · endpoint

Generate or retrieve your unique referral code

Headers

Authorization · string · required

Bearer token or wallet signature for authentication

Response

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

---

Get Referral Stats

GET /api/referral/stats · endpoint

Get detailed statistics about your referral performance

Headers

Authorization · string · required

Bearer token or wallet signature for authentication

Query Parameters

period · string · default: "all"

Time period for stats. Options: 24h, 7d, 30d, all

Response

{
  "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

POST /api/referral/register · endpoint

Register a new user with a referral code

Request Body

referral_code · string · required

The referral code to use for registration

wallet_address · string · required

The wallet address of the new user

Response

{
  "success": true,
  "message": "Successfully registered with referral code",
  "referrer": "0xabc...def"
}

---

Get Referral Leaderboard

GET /api/referral/leaderboard · endpoint

View the top referrers on the platform

Query Parameters

limit · number · default: "10"

Number of top referrers to return (max: 100)

period · string · default: "all"

Time period for leaderboard. Options: 24h, 7d, 30d, all

Response

{
  "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

cURL

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