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!

PreviousSmart Contracts NextIntegration Guide

Last updated 7 months ago

hashtag🚀 Getting Started

hashtagBase URL

hashtagAuthentication

hashtagRate Limits

hashtag📊 Rounds API

hashtagGet Current Round

hashtagGet Round History

hashtagGet Round Details

hashtag🎯 Predictions API

hashtagMake a Prediction

hashtagGet User Predictions

hashtagClaim Rewards

hashtag🤖 AI Analysis API

hashtagGet AI Market Analysis

hashtagGet AI Prediction History

hashtag📈 Market Data API

hashtagGet Current Price

hashtagGet Price History

hashtag🏆 Leaderboard API

hashtagGet Top Predictors

hashtagGet Volume Leaders

hashtag📊 Statistics API

hashtagGet Platform Statistics

hashtagGet User Statistics

hashtagReal-time Events

hashtagRound Updates

hashtagPrice Updates

hashtagAI Analysis Updates

hashtag🔒 Authentication & Security

hashtagAPI Key Management

hashtagWebhook Signatures

hashtag📝 Error Handling

hashtagError Response Format

hashtagCommon Error Codes

hashtag🚀 SDK Examples

hashtagJavaScript/Node.js

hashtagPython

hashtagCurl Examples

hashtag📚 Integration Examples

hashtagTrading Bot Integration

hashtagPortfolio Tracker

🚀 Getting Started

Base URL

Authentication

Rate Limits

📊 Rounds API

Get Current Round

Get Round History

Get Round Details

🎯 Predictions API

Make a Prediction

Get User Predictions

Claim Rewards

🤖 AI Analysis API

Get AI Market Analysis

Get AI Prediction History

📈 Market Data API

Get Current Price

Get Price History

🏆 Leaderboard API

Get Top Predictors

Get Volume Leaders

📊 Statistics API

Get Platform Statistics

Get User Statistics

Real-time Events

Round Updates

Price Updates

AI Analysis Updates

🔒 Authentication & Security

API Key Management

Webhook Signatures

📝 Error Handling

Error Response Format

Common Error Codes

🚀 SDK Examples

JavaScript/Node.js

Python

Curl Examples

📚 Integration Examples

Trading Bot Integration

Portfolio Tracker