Whisky API

The Whisky API provides comprehensive access to gaming analytics, statistics, and real-time data from the Whisky Gaming Protocol. It serves as the data layer for applications that need to display gaming information, track performance, or integrate Whisky data into their systems.

Overview

The Whisky API is a secure, high-performance REST API that indexes blockchain data from the Whisky protocol and provides fast, aggregated access to:

Real-time Analytics: Live statistics and metrics
Historical Data: Game history and event logs
Pool Information: Liquidity pool status and metrics
Player Statistics: Individual player performance data
Platform Analytics: Creator and platform performance

Base URL

https://api.whisky.casino

Authentication

The API is secured for internal use only. All endpoints require a valid API key.

API Key Authentication

Include your API key in one of these ways: Header Method:

X-API-Key: your-api-key-here

Authorization Method:

Authorization: Bearer your-api-key-here

Environment Setup

Add the following to your .env file:

API_KEY=your-secure-api-key-here
HELIUS_API_KEY=your-helius-api-key
SOLANA_RPC_ENDPOINT=your-solana-rpc-endpoint
PORT=3000

Core Endpoints

System Status

Check API Status

GET /status

Response:

{
  "syncing": false,
  "lastSync": "2024-01-15T10:35:00.000Z",
  "totalGames": 1250,
  "totalVolume": 50000.50
}

Get Sync Status

GET /sync/status

Response:

{
  "success": true,
  "data": {
    "totalSignatures": 1250,
    "totalGames": 1200,
    "totalPoolChanges": 50,
    "latestUpdate": {
      "signature": "abc123...",
      "blockTime": 1705312200,
      "timestamp": "2024-01-15T10:30:00.000Z"
    },
    "lastSync": "2024-01-15T10:35:00.000Z"
  }
}

Trigger Manual Sync

POST /sync

Analytics & Statistics

Platform Statistics

GET /stats

Query Parameters:

creator (optional): Filter by specific creator address
startTime (optional): Filter from specific timestamp

Response:

{
  "players": 150,
  "usd_volume": 50000.50,
  "plays": 1200,
  "creators": 5,
  "revenue_usd": 2500.25,
  "player_net_profit_usd": -1500.75,
  "active_players": 25,
  "first_bet_time": 1704067200000
}

Individual Player Stats

GET /player?user=PLAYER_WALLET_ADDRESS

Query Parameters:

user (required): Player wallet address
creator (optional): Filter by specific creator
token (optional): Filter by specific token

Response:

{
  "user": "PLAYER_ADDRESS",
  "total_plays": 45,
  "total_volume_usd": 1250.75,
  "total_profit_usd": -125.50,
  "biggest_win_usd": 500.00,
  "biggest_loss_usd": -100.00,
  "favorite_token": "USDC_MINT_ADDRESS",
  "first_play": 1704067200000,
  "last_play": 1705312200000
}

Top Players Leaderboard

GET /players

Query Parameters:

sortBy (optional): Sort by usd_profit, usd_volume, token_profit, token_volume (default: usd_profit)
limit (optional): Number of results (default: 10)
offset (optional): Pagination offset
creator (optional): Filter by specific creator
token (optional): Filter by specific token
pool (optional): Filter by specific pool
startTime (optional): Filter from specific timestamp

Response:

{
  "results": [
    {
      "user": "PLAYER_ADDRESS",
      "total_plays": 150,
      "usd_volume": 5000.00,
      "usd_profit": 750.50,
      "token_volume": "1000000000",
      "token_profit": "150000000",
      "biggest_win_usd": 1000.00,
      "last_play": 1705312200000
    }
  ],
  "total": 150
}

Game Events & History

Settled Games

GET /events/settledGames

Query Parameters:

page (optional): Page number (default: 0)
itemsPerPage (optional): Items per page (default: 10)
onlyJackpots (optional): Filter only jackpot wins
creator (optional): Filter by specific creator
pool (optional): Filter by specific pool
token (optional): Filter by specific token
user (optional): Filter by specific player
orderBy (optional): Sort by time, multiplier, usd_profit (default: time)
sorting (optional): ASC or DESC (default: DESC)

Response:

{
  "results": [
    {
      "signature": "abc123...",
      "wager": "1000000000",
      "payout": "1500000000",
      "usd_wager": 1.0,
      "usd_profit": 0.5,
      "profit": "500000000",
      "user": "PLAYER_ADDRESS",
      "creator": "CREATOR_ADDRESS",
      "token": "TOKEN_ADDRESS",
      "jackpot": "0",
      "multiplier": 1.5,
      "time": 1705312200000
    }
  ],
  "total": 1200
}

Pool Changes

GET /events/poolChanges?pool=POOL_ADDRESS

Query Parameters:

pool (required): Pool address to filter by

Platform & Creator Data

Top Platforms

GET /platforms

Query Parameters:

limit (optional): Number of results (default: 10)
days (optional): Time period in days (default: 7)
sortBy (optional): Sort by usd_volume, usd_revenue (default: usd_volume)

Response:

{
  "results": [
    {
      "creator": "CREATOR_ADDRESS",
      "usd_volume": 25000.00,
      "usd_revenue": 1250.00,
      "plays": 500,
      "unique_players": 45,
      "last_activity": 1705312200000
    }
  ]
}

Platforms by Pool

GET /platforms-by-pool?pool=POOL_ADDRESS

Token & Pool Data

Top Tokens

GET /tokens

Query Parameters:

creator (optional): Filter by specific creator

Pool Analytics

Get Pool Ratio Changes:

GET /ratio?pool=POOL_ADDRESS

Get Total Pool Volume:

GET /total?pool=POOL_ADDRESS

Get Daily Pool Volume:

GET /daily?pool=POOL_ADDRESS

Chart & Time Series Data

Daily Plays Chart

GET /chart/plays

Response:

{
  "data": [
    {
      "date": "2024-01-15",
      "plays": 150,
      "volume_usd": 5000.00
    }
  ]
}

Daily USD Volume Chart

GET /chart/daily-usd

Query Parameters:

creator (optional): Filter by specific creator

DAO Fee Collection Chart

GET /chart/dao-usd

Query Parameters:

creator (optional): Filter by specific creator

Usage Examples

Quick Health Check

# Check if API is running and synced
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/status"
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/sync/status"

Get Recent Activity

# Get latest games
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/events/settledGames?itemsPerPage=5"

# Get top players
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/players?limit=5"

# Get platform stats
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/stats"

Monitor Specific Pool

# Get pool volume
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/total?pool=YOUR_POOL_ADDRESS"

# Get pool daily activity
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/daily?pool=YOUR_POOL_ADDRESS"

# Get pool ratio changes
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/ratio?pool=YOUR_POOL_ADDRESS"

Track Specific Player

# Get player stats
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/player?user=PLAYER_WALLET_ADDRESS"

# Get player's recent games
curl -H "X-API-Key: your-api-key-here" "https://api.whisky.casino/events/settledGames?user=PLAYER_WALLET_ADDRESS&itemsPerPage=10"

JavaScript/TypeScript Integration

Using Fetch API

class WhiskyAPI {
  private baseUrl: string;
  private apiKey: string;

  constructor(baseUrl: string, apiKey: string) {
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
  }

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

    if (!response.ok) {
      throw new Error(`API request failed: ${response.statusText}`);
    }

    return response.json();
  }

  async getStats(creator?: string) {
    const params = creator ? `?creator=${creator}` : '';
    return this.request(`/stats${params}`);
  }

  async getSettledGames(options: {
    page?: number;
    itemsPerPage?: number;
    creator?: string;
    user?: string;
  } = {}) {
    const params = new URLSearchParams();
    Object.entries(options).forEach(([key, value]) => {
      if (value !== undefined) {
        params.append(key, value.toString());
      }
    });
    
    return this.request(`/events/settledGames?${params.toString()}`);
  }

  async getTopPlayers(options: {
    limit?: number;
    sortBy?: string;
    creator?: string;
  } = {}) {
    const params = new URLSearchParams();
    Object.entries(options).forEach(([key, value]) => {
      if (value !== undefined) {
        params.append(key, value.toString());
      }
    });
    
    return this.request(`/players?${params.toString()}`);
  }
}

// Usage
const api = new WhiskyAPI('https://api.whisky.casino', 'your-api-key');

// Get platform statistics
const stats = await api.getStats();

// Get recent games
const games = await api.getSettledGames({
  itemsPerPage: 10,
  creator: 'CREATOR_ADDRESS'
});

// Get top players
const players = await api.getTopPlayers({
  limit: 20,
  sortBy: 'usd_profit'
});

Using Axios

import axios from 'axios';

const whiskyAPI = axios.create({
  baseURL: 'https://api.whisky.casino',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json',
  },
});

// Get platform statistics
const getStats = async (creator?: string) => {
  const params = creator ? { creator } : {};
  const response = await whiskyAPI.get('/stats', { params });
  return response.data;
};

// Get settled games
const getSettledGames = async (options: {
  page?: number;
  itemsPerPage?: number;
  creator?: string;
  user?: string;
} = {}) => {
  const response = await whiskyAPI.get('/events/settledGames', { params: options });
  return response.data;
};

// Get top players
const getTopPlayers = async (options: {
  limit?: number;
  sortBy?: string;
  creator?: string;
} = {}) => {
  const response = await whiskyAPI.get('/players', { params: options });
  return response.data;
};

Error Handling

The API returns standard HTTP status codes:

200 - Success
400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid API key)
404 - Not Found
429 - Rate Limited
500 - Internal Server Error

Error Response Format

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

Standard Tier: 100 requests per minute
Premium Tier: 1000 requests per minute
Enterprise Tier: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312260

Data Freshness

Real-time Data: Game events and pool changes are indexed within 30 seconds
Analytics Data: Statistics are updated every 5 minutes
Historical Data: Available for the last 12 months
Chart Data: Available for the last 300 days

Best Practices

1. Caching

Implement appropriate caching for frequently accessed data:

// Cache platform stats for 5 minutes
const stats = await cache.get('platform_stats') || await api.getStats();
if (!cache.get('platform_stats')) {
  cache.set('platform_stats', stats, 300); // 5 minutes
}

2. Pagination

Use pagination for large datasets:

const games = await api.getSettledGames({
  page: 0,
  itemsPerPage: 50
});

3. Error Handling

Implement robust error handling:

try {
  const stats = await api.getStats();
} catch (error) {
  if (error.response?.status === 429) {
    // Handle rate limiting
    await delay(1000);
    return await api.getStats();
  }
  throw error;
}

4. Monitoring

Monitor API usage and performance:

const startTime = Date.now();
const stats = await api.getStats();
const responseTime = Date.now() - startTime;

// Log performance metrics
console.log(`API response time: ${responseTime}ms`);

Integration with Other Components

The Whisky API works seamlessly with other Whisky components:

With Whisky Explorer

The Explorer uses the API to display real-time dashboards and analytics.

With Whisky Core SDK

Applications can use both the API for data and the SDK for transactions.

With Whisky React SDK

React applications can fetch data from the API and display it using React components.

Support

For API support and questions:

Documentation: This documentation
Community: Discord Server
Issues: GitHub Issues
Email: support@whisky.casino

​Whisky API

​Overview

​Base URL

​Authentication

​API Key Authentication

​Environment Setup

​Core Endpoints

​System Status

​Check API Status

​Get Sync Status

​Trigger Manual Sync

​Analytics & Statistics

​Platform Statistics

​Individual Player Stats

​Top Players Leaderboard

​Game Events & History

​Settled Games

​Pool Changes

​Platform & Creator Data

​Top Platforms

​Platforms by Pool

​Token & Pool Data

​Top Tokens

​Pool Analytics

​Chart & Time Series Data

​Daily Plays Chart

​Daily USD Volume Chart

​DAO Fee Collection Chart

​Usage Examples

​Quick Health Check

​Get Recent Activity

​Monitor Specific Pool

​Track Specific Player

​JavaScript/TypeScript Integration

​Using Fetch API

​Using Axios

​Error Handling

​Error Response Format

​Rate Limiting

​Data Freshness

​Best Practices

​1. Caching

​2. Pagination

​3. Error Handling

​4. Monitoring

​Integration with Other Components

​With Whisky Explorer

​With Whisky Core SDK

​With Whisky React SDK

​Support

Whisky API

Overview

Base URL

Authentication

API Key Authentication

Environment Setup

Core Endpoints

System Status

Check API Status

Get Sync Status

Trigger Manual Sync

Analytics & Statistics

Platform Statistics

Individual Player Stats

Top Players Leaderboard

Game Events & History

Settled Games

Pool Changes

Platform & Creator Data

Top Platforms

Platforms by Pool

Token & Pool Data

Top Tokens

Pool Analytics

Chart & Time Series Data

Daily Plays Chart

Daily USD Volume Chart

DAO Fee Collection Chart

Usage Examples

Quick Health Check

Get Recent Activity

Monitor Specific Pool

Track Specific Player

JavaScript/TypeScript Integration

Using Fetch API

Using Axios

Error Handling

Error Response Format

Rate Limiting

Data Freshness

Best Practices

1. Caching

2. Pagination

3. Error Handling

4. Monitoring

Integration with Other Components

With Whisky Explorer

With Whisky Core SDK

With Whisky React SDK

Support