ReplyCorp Client API Documentation

Introduction

The ReplyCorp Client API provides secure, authenticated access to profile and leaderboard data for external developers and integrations.

Base URLs

• Production: https://client.api.replycorp.io

• Development: http://localhost:9090 (with header x-client-api: true)

Quick Start

1. Get API Access - Contact support or admin to grant API access to your account

2. Login - Use your ReplyCorp credentials to get a JWT token

3. Create API Key - Generate an API key for external use

4. Use Client API - Make authenticated requests with your API key

---

Authentication & Setup

Step 1: Request API Access

API access must be granted by an administrator. Contact support at [email protected] to request access.

Step 2: Login to Main API

POST https://prod.api.replycorp.io/user/login

curl -X POST https://prod.api.replycorp.io/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 3: Check API Access Status

GET https://prod.api.replycorp.io/user/api-keys

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://prod.api.replycorp.io/user/api-keys

Response (if access granted):

{
  "hasAccess": true,
  "apiKeys": [...]
}

Response (if no access):

{
  "hasAccess": false,
  "message": "API access not authorized. Contact support to request access."
}

Step 4: Create API Key

POST https://prod.api.replycorp.io/user/api-keys

curl -X POST https://prod.api.replycorp.io/user/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "My Integration",
    "description": "External integration for leaderboard data"
  }'

Response:

{
  "id": "api-key-id",
  "name": "My Integration",
  "apiKey": "rcp_4c80f29cdc1fa91c7fbacfffbb07da8aa4d9b828741d74e4370790a010a57300",
  "permissions": ["public"],
  "rateLimit": 1000,
  "message": "API key created successfully"
}

⚠️ Save your API key securely - it won't be shown again!

API Key Management

List Your API Keys

GET https://prod.api.replycorp.io/user/api-keys

Delete API Key

DELETE https://prod.api.replycorp.io/user/api-keys/:id

Limits:

• Maximum 5 API keys per user

• Rate limit: 1000 requests per hour per key

---

Client API Endpoints

All Client API requests require your API key in the X-API-Key header:

curl -H "X-API-Key: rcp_your_api_key_here..." \
  https://client.api.replycorp.io/v1/profiles/profile-name

Get API Key Info

GET /v1/auth/info

curl -H "X-API-Key: rcp_abc123..." \
  https://client.api.replycorp.io/v1/auth/info

Response:

{
  "name": "My Integration",
  "permissions": ["public"],
  "rateLimit": 1000,
  "createdAt": "2025-07-21T18:07:34.308Z",
  "lastUsedAt": "2025-07-21T18:08:28.208Z",
  "user": "[email protected]"
}

Get Profile Information

GET /v1/profiles/:name

curl -H "X-API-Key: rcp_abc123..." \
  https://client.api.replycorp.io/v1/profiles/j-beans

Response:

{
  "id": "campaign-id",
  "name": "J-Beans", 
  "nameSlug": "j-beans",
  "status": "ACTIVE",
  "visibility": "PUBLIC",
  "description": "The value of J-Beans is mysterious and important...",
  "likeReward": 1,
  "repostReward": 2,
  "commentReward": 2,
  "totalFans": 1756,
  "totalEngagement": 4894,
  "totalRewards": 5488,
  "profileLinks": [
    {
      "id": "link-id",
      "url": "https://www.replycorp.io/",
      "type": "link"
    }
  ],
  "enhanced": false,
  "totalHolders": 1756,
  "totalEngagements": 4894
}

Enhanced Field:

• true - You own this campaign (access to sensitive data)

• false - Public access only (no sensitive data)

Get Holders (Leaderboard)

GET /v1/profiles/:name/holders

Query Parameters:

• page (default: 1)

• limit (default: 100, max: 1000)

• search (optional: filter by username)

curl -H "X-API-Key: rcp_abc123..." \
  "https://client.api.replycorp.io/v1/profiles/j-beans/holders?page=1&limit=10&search=crypto"

Response:

{
  "campaign": {
    "id": "campaign-id",
    "name": "J-Beans"
  },
  "holders": [
    {
      "rank": 1,
      "holder": "GrokChecker1",
      "amount": 220,
      "email": null,
      "evmWallet": null, 
      "solanaWallet": null
    },
    {
      "rank": 2,
      "holder": "0xSweDan", 
      "amount": 147,
      "email": null,
      "evmWallet": null,
      "solanaWallet": null
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 352,
    "totalItems": 1756,
    "hasNextPage": true,
    "hasPrevPage": false,
    "limit": 10
  },
  "enhanced": false
}

Sensitive Data Access:

• Public access - email, evmWallet, solanaWallet always return null

• Owner access - Real values shown if users have connected their data

Get Enhanced Stats (Owner Only)

GET /v1/profiles/:name/stats

Only available for campaigns you own.

curl -H "X-API-Key: rcp_abc123..." \
  https://client.api.replycorp.io/v1/profiles/your-campaign/stats

Response (if you own the campaign):

{
  "campaign": {
    "id": "campaign-id",
    "name": "Your Campaign",
    "totalHolders": 224,
    "totalEngagements": 316
  },
  "engagementBreakdown": [
    {
      "_count": { "event_id": 263 },
      "event_type": "LIKE"
    },
    {
      "_count": { "event_id": 24 },
      "event_type": "RETWEET"
    }
  ],
  "topHolders": [
    {
      "holder": "JordanEureka_",
      "amount": 23,
      "email": "[email protected]",
      "evmWallet": "0x123...",
      "solanaWallet": null
    }
  ]
}

Response (if you don't own the campaign):

{
  "error": "Owner access required"
}

---

Access Control & Security

Public vs Owner Access

Data Type	Public Access	Owner Access
Profile Info	✅ Full access	✅ Full access
Leaderboard Rankings	✅ Username, points, rank	✅ Username, points, rank
User Emails	❌ Always null	✅ Real emails (if connected)
User Wallets	❌ Always null	✅ Real wallets (if connected)
Enhanced Stats	❌ Blocked	✅ Full analytics

Ownership Detection

You have owner access to campaigns where you are listed as a participant. This is determined by matching your API key's user ID with the campaign participants.

---

Rate Limiting & Usage

Limits

• Rate Limit: 1000 requests per hour per API key

• Max API Keys: 5 per user

• Max Page Size: 1000 items per request

Usage Tracking

Every API request is logged with:

• Timestamp

• Endpoint called

• Your IP address

• User agent

• API key used

Access usage info via GET /v1/auth/info.

---

Complete Examples

JavaScript/Node.js Example

class ReplyCorpAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://client.api.replycorp.io';
  }

  async request(endpoint) {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.error || response.statusText}`);
    }

    return await response.json();
  }

  async getProfile(name) {
    return await this.request(`/v1/profiles/${name}`);
  }

  async getHolders(name, page = 1, limit = 100, search = '') {
    const params = new URLSearchParams({ 
      page: page.toString(), 
      limit: limit.toString() 
    });
    if (search) params.append('search', search);
    
    return await this.request(`/v1/profiles/${name}/holders?${params}`);
  }

  async getStats(name) {
    return await this.request(`/v1/profiles/${name}/stats`);
  }
}

// Usage
const api = new ReplyCorpAPI('rcp_your_api_key_here...');

try {
  // Get profile info
  const profile = await api.getProfile('j-beans');
  console.log(`${profile.name}: ${profile.totalHolders} holders`);

  // Get leaderboard
  const leaderboard = await api.getHolders('j-beans', 1, 10);
  console.log('Top 10 holders:');
  leaderboard.holders.forEach(holder => {
    console.log(`${holder.rank}. ${holder.holder}: ${holder.amount} points`);
  });

  // Get stats (only works if you own the campaign)
  const stats = await api.getStats('your-campaign');
  console.log('Enhanced analytics:', stats);

} catch (error) {
  console.error('Error:', error.message);
}

Python Example

import requests
import json

class ReplyCorpAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://client.api.replycorp.io'
        self.headers = {
            'X-API-Key': api_key,
            'Content-Type': 'application/json'
        }
    
    def request(self, endpoint):
        response = requests.get(f"{self.base_url}{endpoint}", headers=self.headers)
        response.raise_for_status()
        return response.json()
    
    def get_profile(self, name):
        return self.request(f"/v1/profiles/{name}")
    
    def get_holders(self, name, page=1, limit=100, search=''):
        params = {'page': page, 'limit': limit}
        if search:
            params['search'] = search
        
        endpoint = f"/v1/profiles/{name}/holders"
        response = requests.get(f"{self.base_url}{endpoint}", 
                              headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

# Usage
api = ReplyCorpAPI('rcp_your_api_key_here...')

try:
    # Get profile
    profile = api.get_profile('j-beans')
    print(f"{profile['name']}: {profile['totalHolders']} holders")
    
    # Get top holders
    leaderboard = api.get_holders('j-beans', page=1, limit=10)
    print("Top 10 holders:")
    for holder in leaderboard['holders']:
        print(f"{holder['rank']}. {holder['holder']}: {holder['amount']} points")
        
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

---

Error Handling

Error Response Format

{
  "error": "Error description here"
}

HTTP Status Codes

• 200 - Success

• 400 - Bad Request (invalid parameters)

• 401 - Unauthorized (invalid/missing API key)

• 403 - Forbidden (insufficient permissions)

• 404 - Not Found (profile doesn't exist)

• 429 - Rate Limit Exceeded

• 500 - Internal Server Error

Common Errors

Missing API Key

{
  "error": "API key required"
}

Invalid API Key

{
  "error": "Invalid API key"
}

Rate Limited

{
  "error": "Rate limit exceeded. Try again in 3600 seconds."
}

Owner Access Required

{
  "error": "Owner access required"
}

Profile Not Found

{
  "error": "Profile not found"
}

---

Migration Guide

From Old Internal API

❌ Old Way (Deprecated):

// This relied on referer spoofing - not secure
fetch('https://prod.api.replycorp.io/replypoint-profile/j-beans/holders?page=1&limit=100', {
  headers: {
    'Referer': 'https://app.replycorp.io'
  }
})

✅ New Way (Recommended):

// Clean, authenticated, secure API
fetch('https://client.api.replycorp.io/v1/profiles/j-beans/holders?page=1&limit=100', {
  headers: {
    'X-API-Key': 'rcp_your_api_key_here...'
  }
})

Benefits of New API

• ✅ Proper authentication with API keys

• ✅ Rate limiting and usage tracking

• ✅ Better security with ownership-based access control

• ✅ Consistent responses with comprehensive error handling

• ✅ Enhanced features for campaign owners

• ✅ Future-proof architecture

---

Support & Contact

• Technical Support: [email protected]

• API Access Requests: [email protected]

• Documentation Issues: Create an issue in our GitHub repository

Changelog

v1.2.0 (Current)

• ✅ Ownership-based access control - Enhanced data only for campaign owners

• ✅ Comprehensive API key management - Create, list, delete keys via main API

• ✅ Usage tracking - Full audit trail of API requests

• ✅ Enhanced security - Protected sensitive user data

• ✅ Improved error messages - Clear ownership and permission errors

v1.1.0

• ✅ Enhanced stats endpoint for detailed analytics

• ✅ Better pagination with comprehensive metadata

• ✅ Search functionality for filtering holders

v1.0.0

• ✅ Initial release with profile and holder endpoints

• ✅ Basic API key authentication

• ✅ Rate limiting and error handling

---

Last updated: July 21, 2025