CastDex Voting API Documentation

Welcome to the CastDex Voting API! This API provides read-only access to voting data from the CastDex platform, allowing you to retrieve token statistics, trending information, and voting analytics.

Quick Start

Base URL

https://castdex.vercel.app/api/external/votes

Authentication

All API requests require authentication using an API key in the request header:

X-API-Key: your_64_character_api_key_here

Example Request

curl -H "X-API-Key: your_64_character_api_key_here" \
  "https://castdex.vercel.app/api/external/votes/stats?token_id=solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

---

Authentication

The CastDex Voting API uses API key authentication. Your API key is a unique 64-character alphanumeric string that identifies your application and tracks usage.

Header Formats

The API accepts API keys in multiple header formats:

Header	Format	Example
X-API-Key	Direct key	X-API-Key: abc123...xyz789
Authorization	Bearer token	Authorization: Bearer abc123...xyz789
API-Key	Direct key	API-Key: abc123...xyz789

API Key Requirements

• Length: Exactly 64 characters

• Format: Alphanumeric only (a-z, A-Z, 0-9)

• Example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567cde890fgh

Getting an API Key

Contact the CastDex team to request an API key for your application. Please provide:

• Application name and description

• Expected usage volume

• Integration timeline

• Technical contact information

---

Rate Limits

To ensure fair usage and system stability, the API implements rate limiting per API key:

Window	Default Limit	Header
Per Minute	1,000 requests	X-RateLimit-Remaining
Per Hour	10,000 requests	X-RateLimit-Reset
Per Day	100,000 requests	X-RateLimit-Window

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Remaining: 999
X-RateLimit-Reset: 2025-07-17T23:00:00.000Z
X-RateLimit-Window: minute

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "Rate limit exceeded for minute. Try again after 2025-07-17T23:00:00.000Z"
}

Best Practices:

• Monitor the X-RateLimit-Remaining header

• Implement exponential backoff for retries

• Cache responses when possible

• Contact support if you need higher limits

---

API Endpoints

1. Token Statistics

Get detailed voting statistics for one or more tokens.

Endpoint: GET /stats

Parameters

Parameter	Type	Required	Description
token_id	string	Yes*	Single token identifier
token_ids	string	Yes*	Comma-separated list of token IDs (max 100)
period	string	No	Time period: 1h, 24h, 7d, 30d, all (default: 24h)
group_by	string	No	Group results: hour, day, user
include_details	boolean	No	Include detailed vote information (default: false)

*Either token_id or token_ids is required

Examples

Single Token:

curl -H "X-API-Key: your_api_key" \
  "https://castdex.vercel.app/api/external/votes/stats?token_id=solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&period=24h"

Multiple Tokens:

curl -H "X-API-Key: your_api_key" \
  "https://castdex.vercel.app/api/external/votes/stats?token_ids=token1,token2,token3&period=7d"

Grouped by Hour:

curl -H "X-API-Key: your_api_key" \
  "https://castdex.vercel.app/api/external/votes/stats?token_id=example_token&group_by=hour&period=24h"

Response Format

Basic Response:

{
  "success": true,
  "data": {
    "solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": {
      "token_id": "solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "likes": 45,
      "rockets": 23,
      "total": 68,
      "unique_voters": 32,
      "unique_wallets": 30
    }
  },
  "meta": {
    "period": "24h",
    "tokens_requested": 1,
    "total_votes": 68,
    "query_time": "2025-07-17T22:15:00.000Z"
  }
}

Grouped by Hour Response:

{
  "success": true,
  "data": [
    {
      "timestamp": "2025-07-17T22:00:00Z",
      "total_votes": 15,
      "likes": 8,
      "rockets": 7,
      "tokens": {
        "token_id_1": {"likes": 5, "rockets": 3, "total": 8},
        "token_id_2": {"likes": 3, "rockets": 4, "total": 7}
      }
    }
  ],
  "meta": {
    "period": "24h",
    "group_by": "hour",
    "query_time": "2025-07-17T22:15:00.000Z"
  }
}

2. Trending Tokens

Get currently trending tokens based on voting activity.

Endpoint: GET /trending

Parameters

Parameter	Type	Required	Description
period	string	No	Time period: 1h, 24h, 7d (default: 24h)
type	string	No	Sort by: total, likes, rockets (default: total)
limit	integer	No	Number of tokens to return (max 100, default: 10)

Examples

Default Trending:

curl -H "X-API-Key: your_api_key" \
  "https://castdex.vercel.app/api/external/votes/trending"

Trending by Rockets (7-day):

curl -H "X-API-Key: your_api_key" \
  "https://castdex.vercel.app/api/external/votes/trending?period=7d&type=rockets&limit=20"

Response Format

{
  "success": true,
  "data": [
    {
      "token_id": "solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "likes": 120,
      "rockets": 45,
      "total": 165,
      "lastVote": "2025-07-17T22:15:00.000Z"
    },
    {
      "token_id": "base_0x1234567890abcdef1234567890abcdef12345678",
      "likes": 89,
      "rockets": 67,
      "total": 156,
      "lastVote": "2025-07-17T22:10:00.000Z"
    }
  ],
  "meta": {
    "period": "24h",
    "type": "total",
    "limit": 10,
    "total_tokens": 43,
    "query_time": "2025-07-17T22:15:00.000Z"
  }
}

---

Response Format

All API responses follow a consistent JSON structure:

Success Response

{
  "success": true,
  "data": { /* endpoint-specific data */ },
  "meta": {
    "query_time": "2025-07-17T22:15:00.000Z",
    /* additional metadata */
  }
}

Error Response

{
  "success": false,
  "error": "Error description"
}

Common HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid parameters or missing required fields
401	Unauthorized	Invalid or missing API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)

---

Code Examples

JavaScript/Node.js

const API_KEY = 'your_64_character_api_key_here';
const BASE_URL = 'https://castdex.vercel.app/api/external/votes';

async function getTokenStats(tokenId, period = '24h') {
  try {
    const response = await fetch(
      `${BASE_URL}/stats?token_id=${tokenId}&period=${period}`,
      {
        headers: {
          'X-API-Key': API_KEY
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    if (!data.success) {
      throw new Error(data.error);
    }
    
    return data.data;
  } catch (error) {
    console.error('Error fetching token stats:', error);
    throw error;
  }
}

async function getTrendingTokens(limit = 10) {
  try {
    const response = await fetch(
      `${BASE_URL}/trending?limit=${limit}`,
      {
        headers: {
          'X-API-Key': API_KEY
        }
      }
    );
    
    const data = await response.json();
    return data.success ? data.data : null;
  } catch (error) {
    console.error('Error fetching trending tokens:', error);
    return null;
  }
}

// Usage examples
getTokenStats('solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v')
  .then(stats => console.log('Token stats:', stats))
  .catch(error => console.error(error));

getTrendingTokens(5)
  .then(trending => console.log('Top 5 trending:', trending))
  .catch(error => console.error(error));

Python

import requests
import json

API_KEY = 'your_64_character_api_key_here'
BASE_URL = 'https://castdex.vercel.app/api/external/votes'

class CastDexAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.headers = {'X-API-Key': api_key}
    
    def get_token_stats(self, token_id=None, token_ids=None, period='24h', group_by=None):
        """Get token statistics"""
        url = f'{BASE_URL}/stats'
        params = {'period': period}
        
        if token_id:
            params['token_id'] = token_id
        elif token_ids:
            params['token_ids'] = ','.join(token_ids)
        else:
            raise ValueError("Either token_id or token_ids must be provided")
        
        if group_by:
            params['group_by'] = group_by
        
        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        
        data = response.json()
        if not data['success']:
            raise Exception(data['error'])
        
        return data['data']
    
    def get_trending_tokens(self, period='24h', vote_type='total', limit=10):
        """Get trending tokens"""
        url = f'{BASE_URL}/trending'
        params = {
            'period': period,
            'type': vote_type,
            'limit': limit
        }
        
        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        
        data = response.json()
        if not data['success']:
            raise Exception(data['error'])
        
        return data['data']

# Usage examples
api = CastDexAPI(API_KEY)

try:
    # Get stats for a single token
    stats = api.get_token_stats(
        token_id='solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
        period='7d'
    )
    print(f"Token stats: {json.dumps(stats, indent=2)}")
    
    # Get trending tokens
    trending = api.get_trending_tokens(period='24h', limit=5)
    print(f"Top 5 trending: {json.dumps(trending, indent=2)}")
    
    # Get multiple token stats
    multi_stats = api.get_token_stats(
        token_ids=['token1', 'token2', 'token3'],
        period='24h'
    )
    print(f"Multiple token stats: {json.dumps(multi_stats, indent=2)}")
    
except Exception as e:
    print(f"API Error: {e}")

PHP

<?php

class CastDexAPI {
    private $apiKey;
    private $baseUrl = 'https://castdex.vercel.app/api/external/votes';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    private function makeRequest($endpoint, $params = []) {
        $url = $this->baseUrl . $endpoint;
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json'
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode !== 200) {
            throw new Exception("HTTP Error: $httpCode");
        }
        
        $data = json_decode($response, true);
        if (!$data['success']) {
            throw new Exception($data['error']);
        }
        
        return $data['data'];
    }
    
    public function getTokenStats($tokenId = null, $tokenIds = null, $period = '24h', $groupBy = null) {
        $params = ['period' => $period];
        
        if ($tokenId) {
            $params['token_id'] = $tokenId;
        } elseif ($tokenIds) {
            $params['token_ids'] = implode(',', $tokenIds);
        } else {
            throw new Exception("Either tokenId or tokenIds must be provided");
        }
        
        if ($groupBy) {
            $params['group_by'] = $groupBy;
        }
        
        return $this->makeRequest('/stats', $params);
    }
    
    public function getTrendingTokens($period = '24h', $type = 'total', $limit = 10) {
        $params = [
            'period' => $period,
            'type' => $type,
            'limit' => $limit
        ];
        
        return $this->makeRequest('/trending', $params);
    }
}

// Usage example
$api = new CastDexAPI('your_64_character_api_key_here');

try {
    // Get token statistics
    $stats = $api->getTokenStats(
        'solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
        null,
        '24h'
    );
    echo "Token stats: " . json_encode($stats, JSON_PRETTY_PRINT) . "\n";
    
    // Get trending tokens
    $trending = $api->getTrendingTokens('24h', 'total', 5);
    echo "Trending: " . json_encode($trending, JSON_PRETTY_PRINT) . "\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

?>

cURL

#!/bin/bash

API_KEY="your_64_character_api_key_here"
BASE_URL="https://castdex.vercel.app/api/external/votes"

# Function to make API calls
call_api() {
    local endpoint="$1"
    local params="$2"
    
    curl -s \
        -H "X-API-Key: $API_KEY" \
        -H "Content-Type: application/json" \
        "$BASE_URL$endpoint?$params"
}

# Get token statistics
echo "=== Token Statistics ==="
call_api "/stats" "token_id=solana_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&period=24h" | jq '.'

echo -e "\n=== Multiple Token Statistics ==="
call_api "/stats" "token_ids=token1,token2,token3&period=7d" | jq '.'

echo -e "\n=== Trending Tokens ==="
call_api "/trending" "period=24h&type=total&limit=10" | jq '.'

echo -e "\n=== Trending by Rockets ==="
call_api "/trending" "period=7d&type=rockets&limit=5" | jq '.'

echo -e "\n=== Hourly Breakdown ==="
call_api "/stats" "token_id=example_token&group_by=hour&period=24h" | jq '.'

---

Best Practices

1. Error Handling

Always check the success field in API responses:

const response = await fetch(url, { headers: { 'X-API-Key': apiKey } });
const data = await response.json();

if (!data.success) {
  console.error('API Error:', data.error);
  // Handle error appropriately
  return;
}

// Process successful response
console.log('Data:', data.data);

2. Rate Limit Management

Monitor rate limit headers and implement backoff:

function checkRateLimit(response) {
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');
  
  if (remaining && parseInt(remaining) < 10) {
    console.warn(`Low rate limit: ${remaining} requests remaining`);
    console.warn(`Resets at: ${reset}`);
  }
}

3. Caching

Cache responses to reduce API calls:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedStats(tokenId, period) {
  const cacheKey = `${tokenId}-${period}`;
  const cached = cache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getTokenStats(tokenId, period);
  cache.set(cacheKey, { data, timestamp: Date.now() });
  
  return data;
}

4. Retry Logic

Implement exponential backoff for transient errors:

async function apiCallWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

5. Batch Requests

Use the token_ids parameter to request multiple tokens efficiently:

// Instead of multiple requests
const stats1 = await getTokenStats('token1');
const stats2 = await getTokenStats('token2');
const stats3 = await getTokenStats('token3');

// Use a single batch request
const allStats = await getTokenStats(null, ['token1', 'token2', 'token3']);

---

Common Use Cases

1. Token Dashboard

Display comprehensive token information:

async function createTokenDashboard(tokenId) {
  try {
    const [stats24h, stats7d, trending] = await Promise.all([
      getTokenStats(tokenId, '24h'),
      getTokenStats(tokenId, '7d'), 
      getTrendingTokens(100) // Get rank in top 100
    ]);
    
    const tokenRank = trending.findIndex(t => t.token_id === tokenId) + 1;
    
    return {
      token_id: tokenId,
      daily_stats: stats24h[tokenId],
      weekly_stats: stats7d[tokenId],
      trending_rank: tokenRank || null,
      last_updated: new Date().toISOString()
    };
  } catch (error) {
    console.error('Dashboard error:', error);
    throw error;
  }
}

2. Trending Analysis

Track trending patterns over time:

async function analyzeTrending() {
  const periods = ['1h', '24h', '7d'];
  const types = ['total', 'likes', 'rockets'];
  
  const analysis = {};
  
  for (const period of periods) {
    analysis[period] = {};
    for (const type of types) {
      analysis[period][type] = await getTrendingTokens(period, type, 20);
    }
  }
  
  return analysis;
}

3. Portfolio Tracking

Monitor multiple tokens for a portfolio:

async function trackPortfolio(tokenIds) {
  const portfolioStats = await getTokenStats(null, tokenIds, '24h');
  
  return Object.values(portfolioStats).map(token => ({
    token_id: token.token_id,
    total_votes: token.total,
    engagement_rate: (token.total / token.unique_voters).toFixed(2),
    like_ratio: (token.likes / token.total * 100).toFixed(1) + '%',
    rocket_ratio: (token.rockets / token.total * 100).toFixed(1) + '%'
  }));
}

---

Troubleshooting

Common Issues

Authentication Errors (401)

{
  "success": false,
  "error": "Invalid or missing API key"
}

Solutions:

• Verify your API key is exactly 64 alphanumeric characters

• Ensure the API key is included in the request header

• Check that your API key is active and not expired

• Contact support if the issue persists

Rate Limit Exceeded (429)

{
  "success": false,
  "error": "Rate limit exceeded for minute. Try again after 2025-07-17T23:00:00.000Z"
}

Solutions:

• Implement request throttling in your application

• Add retry logic with exponential backoff

• Cache responses to reduce API calls

• Contact support to discuss higher rate limits

Bad Request (400)

{
  "success": false,
  "error": "Either token_id or token_ids parameter is required"
}

Solutions:

• Check that all required parameters are included

• Validate parameter formats (e.g., period values)

• Ensure token_ids list doesn't exceed 100 tokens

• Review the API documentation for correct parameter usage

Debug Checklist

1. API Key Format: Verify 64 alphanumeric characters

2. Headers: Ensure API key is in the correct header

3. URL: Check the base URL and endpoint paths

4. Parameters: Validate all parameter names and values

5. Rate Limits: Monitor usage and implement proper throttling

6. Response Handling: Always check the success field

---

Support

Getting Help

• Documentation: This guide covers all API functionality

• Status Page: Check [status.castdex.com] for system status

• Support Email: [[email protected]] for technical assistance

Reporting Issues

When reporting issues, please include:

• Your API key (first 10 characters only)

• Request URL and parameters

• Response received

• Timestamp of the issue

• Programming language/framework used

Feature Requests

We're always looking to improve the API. Submit feature requests to [[email protected]] with:

• Detailed description of the requested feature

• Use case explanation

• Expected response format

• Priority level for your integration

---

Changelog

Version 1.0 (July 2025)

• Initial API release

• Token statistics endpoint

• Trending tokens endpoint

• API key authentication

• Rate limiting implementation

• Comprehensive documentation

---

Last Updated: July 17, 2025 API Version: 1.0