API Reference

Complete API documentation for IllumindGame platform. Learn how to integrate our prediction platform into your applications.

🚀 Getting Started

Base URL

Production: https://api.illumindgame.io/v1
Testnet: https://api-testnet.illumindgame.io/v1

Authentication

// API Key Authentication
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

Rate Limits

Endpoint Type	Limit	Window
Public	100 requests	1 minute
Authenticated	1000 requests	1 minute
WebSocket	10 connections	Per IP

📊 Rounds API

Get Current Round

Get information about the active prediction round.

GET /api/rounds/current

Response:

{
  "success": true,
  "data": {
    "roundId": 1247,
    "startTime": "2025-01-15T10:30:00Z",
    "endTime": "2025-01-15T10:35:00Z",
    "priceAtStart": 248750,
    "status": "active",
    "totalUpAmount": "15000000000000000000000",
    "totalDownAmount": "8500000000000000000000",
    "participants": 142,
    "timeRemaining": 187,
    "aiAnalysis": {
      "confidence": 73,
      "direction": "UP",
      "riskLevel": "medium"
    }
  }
}

Get Round History

Retrieve historical round data with pagination.

GET /api/rounds/history?page=1&limit=20&status=resolved

Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (max: 100)
status	string	Filter by status: active, resolved, all

Response:

{
  "success": true,
  "data": {
    "rounds": [
      {
        "roundId": 1246,
        "startTime": "2025-01-15T10:25:00Z",
        "endTime": "2025-01-15T10:30:00Z",
        "priceAtStart": 248200,
        "priceAtEnd": 248750,
        "winner": "UP",
        "totalPool": "23500000000000000000000",
        "upPredictions": "15000000000000000000000",
        "downPredictions": "8500000000000000000000",
        "participants": 89
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1246,
      "totalPages": 63
    }
  }
}

Get Round Details

Get detailed information about a specific round.

GET /api/rounds/{roundId}

Response:

{
  "success": true,
  "data": {
    "roundId": 1246,
    "startTime": "2025-01-15T10:25:00Z",
    "endTime": "2025-01-15T10:30:00Z",
    "priceAtStart": 248200,
    "priceAtEnd": 248750,
    "status": "resolved",
    "winner": "UP",
    "priceChange": 550,
    "priceChangePercent": 0.22,
    "totalPool": "23500000000000000000000",
    "upAmount": "15000000000000000000000",
    "downAmount": "8500000000000000000000",
    "participants": 89,
    "rewardDistributed": "21150000000000000000000",
    "platformFee": "1880000000000000000000",
    "burned": "470000000000000000000",
    "aiAnalysis": {
      "confidence": 78,
      "direction": "UP",
      "factors": [
        "Strong buying pressure",
        "Positive sentiment signals",
        "Technical breakout pattern"
      ]
    }
  }
}

🎯 Predictions API

Make a Prediction

Submit a prediction for the current round.

POST /api/predictions

Request Body:

{
  "roundId": 1247,
  "direction": "UP",
  "amount": "1000000000000000000000",
  "signature": "0x...",
  "userAddress": "0x742d35Cc6635C0532925a3b8D"
}

Parameters:

Parameter	Type	Required	Description
roundId	integer	Yes	Current round ID
direction	string	Yes	UP or DOWN
amount	string	Yes	Amount in wei (18 decimals)
signature	string	Yes	Wallet signature
userAddress	string	Yes	User's wallet address

Response:

{
  "success": true,
  "data": {
    "predictionId": "pred_12470001",
    "roundId": 1247,
    "userAddress": "0x742d35Cc6635C0532925a3b8D",
    "direction": "UP",
    "amount": "1000000000000000000000",
    "timestamp": "2025-01-15T10:31:23Z",
    "txHash": "0x8f3e2c1d9b4a7c6e5f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
    "expectedReward": "1850000000000000000000",
    "aiConfidence": 73
  }
}

Get User Predictions

Retrieve all predictions for a specific user.

GET /api/predictions/user/{address}?page=1&limit=50&status=all

Parameters:

Parameter	Type	Description
page	integer	Page number
limit	integer	Results per page (max: 100)
status	string	active, won, lost, claimed, all

Response:

{
  "success": true,
  "data": {
    "predictions": [
      {
        "predictionId": "pred_12460001",
        "roundId": 1246,
        "direction": "UP",
        "amount": "1000000000000000000000",
        "status": "won",
        "reward": "1850000000000000000000",
        "claimed": true,
        "claimedAt": "2025-01-15T10:30:15Z",
        "profit": "850000000000000000000",
        "timestamp": "2025-01-15T10:26:23Z"
      }
    ],
    "statistics": {
      "totalPredictions": 156,
      "successfulPredictions": 89,
      "accuracy": 57.05,
      "totalStaked": "156000000000000000000000",
      "totalRewards": "178500000000000000000000",
      "netProfit": "22500000000000000000000"
    },
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 156,
      "totalPages": 4
    }
  }
}

Claim Rewards

Claim rewards for won predictions.

POST /api/predictions/claim

Request Body:

{
  "predictionIds": ["pred_12460001", "pred_12450012"],
  "userAddress": "0x742d35Cc6635C0532925a3b8D",
  "signature": "0x..."
}

Response:

{
  "success": true,
  "data": {
    "claimedPredictions": 2,
    "totalReward": "3420000000000000000000",
    "txHash": "0x...",
    "gasUsed": "184320"
  }
}

🤖 AI Analysis API

Get AI Market Analysis

Get current AI analysis for market conditions.

GET /api/ai/analysis

Response:

{
  "success": true,
  "data": {
    "timestamp": "2025-01-15T10:31:45Z",
    "currentPrice": 248750,
    "analysis": {
      "direction": "UP",
      "confidence": 73,
      "riskLevel": "medium",
      "timeframe": "5min",
      "targetPrice": 249200
    },
    "technicalIndicators": {
      "rsi": 58.5,
      "macd": {
        "value": -2.3,
        "signal": -3.1,
        "histogram": 0.8
      },
      "bollingerBands": {
        "upper": 249500,
        "middle": 248200,
        "lower": 246900
      },
      "sma": {
        "sma20": 248100,
        "sma50": 247800
      }
    },
    "sentiment": {
      "overall": 68,
      "twitter": 72,
      "news": 65,
      "reddit": 70,
      "fear_greed_index": 55
    },
    "factors": [
      "RSI showing oversold recovery",
      "MACD bullish crossover detected",
      "Strong social sentiment",
      "Volume above average"
    ],
    "risks": [
      "Approaching resistance level",
      "High volatility period"
    ]
  }
}

Get AI Prediction History

Retrieve historical AI predictions and their accuracy.

GET /api/ai/history?timeframe=24h&limit=100

Response:

{
  "success": true,
  "data": {
    "predictions": [
      {
        "timestamp": "2025-01-15T10:25:00Z",
        "roundId": 1246,
        "prediction": "UP",
        "confidence": 78,
        "startPrice": 248200,
        "actualPrice": 248750,
        "correct": true,
        "accuracy": 0.78
      }
    ],
    "summary": {
      "totalPredictions": 288,
      "correctPredictions": 198,
      "accuracy": 68.75,
      "averageConfidence": 71.2,
      "timeframe": "24h"
    }
  }
}

📈 Market Data API

Get Current Price

Get real-time ETH/USDT price.

GET /api/market/price

Response:

{
  "success": true,
  "data": {
    "symbol": "ETH/USDT",
    "price": 248750,
    "timestamp": "2025-01-15T10:31:45Z",
    "change24h": 1250,
    "changePercent24h": 0.51,
    "volume24h": "1250000000",
    "high24h": 249800,
    "low24h": 246500
  }
}

Get Price History

Get historical price data with different intervals.

GET /api/market/history?interval=5m&limit=100

Parameters:

Parameter	Type	Description
interval	string	1m, 5m, 15m, 1h, 4h, 1d
limit	integer	Number of candles (max: 1000)

Response:

{
  "success": true,
  "data": {
    "symbol": "ETH/USDT",
    "interval": "5m",
    "candles": [
      {
        "timestamp": "2025-01-15T10:30:00Z",
        "open": 248200,
        "high": 248800,
        "low": 248100,
        "close": 248750,
        "volume": "2500000"
      }
    ]
  }
}

🏆 Leaderboard API

Get Top Predictors

Get leaderboard of most accurate predictors.

GET /api/leaderboard/accuracy?period=30d&limit=50

Parameters:

Parameter	Type	Description
period	string	24h, 7d, 30d, all
limit	integer	Number of users (max: 100)

Response:

{
  "success": true,
  "data": {
    "period": "30d",
    "leaderboard": [
      {
        "rank": 1,
        "address": "0x742d35Cc6635C0532925a3b8D",
        "username": "CryptoAI_Master",
        "accuracy": 89.2,
        "totalPredictions": 156,
        "successfulPredictions": 139,
        "totalProfit": "22500000000000000000000",
        "currentStreak": 12
      }
    ]
  }
}

Get Volume Leaders

Get users with highest prediction volumes.

GET /api/leaderboard/volume?period=30d&limit=50

Response:

{
  "success": true,
  "data": {
    "period": "30d",
    "leaderboard": [
      {
        "rank": 1,
        "address": "0x742d35Cc6635C0532925a3b8D",
        "username": "WhalePredictor",
        "totalVolume": "50000000000000000000000",
        "totalPredictions": 234,
        "averageStake": "213675213675213675213",
        "totalProfit": "15200000000000000000000"
      }
    ]
  }
}

📊 Statistics API

Get Platform Statistics

Get overall platform metrics.

GET /api/stats/platform

Response:

{
  "success": true,
  "data": {
    "totalUsers": 25420,
    "activeUsers24h": 3240,
    "totalRounds": 50247,
    "totalPredictions": 2547890,
    "totalVolume": "50000000000000000000000000",
    "totalRewardsDistributed": "45000000000000000000000000",
    "totalBurned": "2500000000000000000000000",
    "averageAccuracy": 52.3,
    "platformFees": "4000000000000000000000000",
    "circulatingSupply": "997500000000000000000000000"
  }
}

Get User Statistics

Get detailed statistics for a specific user.

GET /api/stats/user/{address}

Response:

{
  "success": true,
  "data": {
    "address": "0x742d35Cc6635C0532925a3b8D",
    "totalPredictions": 156,
    "successfulPredictions": 89,
    "accuracy": 57.05,
    "currentStreak": 3,
    "longestStreak": 12,
    "totalStaked": "156000000000000000000000",
    "totalRewards": "178500000000000000000000",
    "netProfit": "22500000000000000000000",
    "averageStake": "1000000000000000000000",
    "favoriteDirection": "UP",
    "bestPerformanceTimeframe": "14:00-16:00 UTC",
    "joinDate": "2024-11-15T08:30:00Z",
    "rank": {
      "accuracy": 45,
      "volume": 128,
      "profit": 67
    }
  }
}

Real-time Events

Round Updates

{
  "type": "round_update",
  "data": {
    "roundId": 1247,
    "timeRemaining": 125,
    "totalUpAmount": "16500000000000000000000",
    "totalDownAmount": "9200000000000000000000",
    "participants": 156
  }
}

Price Updates

{
  "type": "price_update",
  "data": {
    "price": 248850,
    "change": 100,
    "changePercent": 0.04,
    "timestamp": "2025-01-15T10:32:15Z"
  }
}

AI Analysis Updates

{
  "type": "ai_update",
  "data": {
    "confidence": 75,
    "direction": "UP",
    "riskLevel": "medium",
    "factors": ["Strong momentum", "Positive sentiment"]
  }
}

🔒 Authentication & Security

API Key Management

POST /api/auth/keys

Request Body:

{
  "name": "My Trading Bot",
  "permissions": ["read", "trade"],
  "ipWhitelist": ["192.168.1.1", "10.0.0.1"]
}

Webhook Signatures

Verify webhook authenticity using HMAC-SHA256:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return signature === computedSignature;
}

📝 Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_ROUND",
    "message": "Round does not exist or has expired",
    "details": {
      "roundId": 9999,
      "currentRound": 1247
    }
  }
}

Common Error Codes

Code	Description
INVALID_API_KEY	API key is invalid or expired
RATE_LIMIT_EXCEEDED	Too many requests
INVALID_ROUND	Round ID does not exist
ROUND_EXPIRED	Round has already ended
INSUFFICIENT_BALANCE	Not enough tokens
INVALID_SIGNATURE	Wallet signature verification failed
PREDICTION_EXISTS	User already predicted for this round

🚀 SDK Examples

JavaScript/Node.js

const IllumindAPI = require('@illumindgame/sdk');

const client = new IllumindAPI({
  apiKey: 'your-api-key',
  network: 'mainnet' // or 'testnet'
});

// Get current round
const currentRound = await client.rounds.getCurrent();

// Make prediction
const prediction = await client.predictions.create({
  roundId: currentRound.roundId,
  direction: 'UP',
  amount: '1000000000000000000000' // 1000 ILLUMIND
});

// Subscribe to real-time updates
client.ws.subscribe('rounds', (data) => {
  console.log('Round update:', data);
});

Python

from illumind_sdk import IllumindClient

client = IllumindClient(
    api_key='your-api-key',
    network='mainnet'
)

# Get AI analysis
analysis = client.ai.get_analysis()
print(f"AI Confidence: {analysis['confidence']}%")

# Get user statistics
stats = client.stats.get_user('0x742d35Cc6635C0532925a3b8D')
print(f"Accuracy: {stats['accuracy']}%")

Curl Examples

# Get current round
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.illumindgame.io/v1/api/rounds/current

# Make prediction
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"roundId":1247,"direction":"UP","amount":"1000000000000000000000"}' \
  https://api.illumindgame.io/v1/api/predictions

📚 Integration Examples

Trading Bot Integration

class IllumindTradingBot {
  constructor(apiKey) {
    this.client = new IllumindAPI({ apiKey });
  }
  
  async analyze() {
    const aiAnalysis = await this.client.ai.getAnalysis();
    const currentRound = await this.client.rounds.getCurrent();
    
    // Only trade with high confidence
    if (aiAnalysis.confidence > 75) {
      await this.makePrediction(currentRound.roundId, aiAnalysis.direction);
    }
  }
  
  async makePrediction(roundId, direction) {
    const amount = this.calculateStakeSize();
    
    return await this.client.predictions.create({
      roundId,
      direction,
      amount
    });
  }
}

Portfolio Tracker

class PortfolioTracker {
  async getPortfolioSummary(userAddress) {
    const [predictions, stats] = await Promise.all([
      this.client.predictions.getUser(userAddress),
      this.client.stats.getUser(userAddress)
    ]);
    
    return {
      totalValue: stats.totalRewards,
      profit: stats.netProfit,
      accuracy: stats.accuracy,
      recentPredictions: predictions.predictions.slice(0, 10)
    };
  }
}

---

Ready to start building? Check out our Integration Guide for detailed examples!