API Reference

The Open Game Protocol API provides endpoints for game management, player points, rewards, and token operations.

Live API Documentation

Interactive Swagger UI: https://api.opengameprotocol.com/api-reference

The Swagger documentation is auto-generated from the API source code and always reflects the current implementation. Use it to:

• Explore all available endpoints

• See request/response schemas

• Test endpoints directly in the browser

Authentication

HMAC Authentication

Most developer-facing endpoints require HMAC-SHA256 authentication. Include the following header:

Authorization: HMAC-SHA256 apiKey=<your-api-key> signature=<hmac-signature> timestamp=<unix-timestamp>

Components:

• apiKey - Your user API key (get from dashboard)

• signature - HMAC-SHA256 of method + path + timestamp using your secret key

• timestamp - Unix timestamp in milliseconds (must be within 5 minutes)

Generate Signature:

import { createHmac } from 'crypto';

function generateSignature(
  method: string,
  path: string,
  timestamp: number,
  secretKey: string
): string {
  const message = `${method}${path}${timestamp}`;
  return createHmac('sha256', secretKey)
    .update(message)
    .digest('hex');
}

// Example
const timestamp = Date.now();
const signature = generateSignature('POST', '/games', timestamp, 'your-secret-key');

Or use the helper endpoint:

// Get a pre-generated signature from the API
const response = await fetch(
  'https://api.opengameprotocol.com/user/hmac-signature',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      method: 'POST',
      path: '/games'
    })
  }
);
const { signature, timestamp, apiKey } = await response.json();

Player Authentication

For SDK/player endpoints, use session tokens obtained via the SDK initialization flow.

Main Endpoint Categories

Games (/games)

• GET /games - List all games with pagination and sorting

• POST /games - Register a new game (multipart form-data)

• POST /games/update/:gameId - Update a game

• GET /games/id/:id - Get game by ID

• GET /games/me - Get your games

• POST /games/batch/token-ids - Get games by token addresses

• GET /games/token-id/:tokenId/full - Get full games for a token

Play (/play)

• POST /play/dev/batch-save-points - Batch save player points

• GET /play/dev/points - Get player points

• GET /play/dev/leaderboard/:gameId - Get game leaderboard

User (/user)

• GET /user/me - Get current user

• POST /user/hmac-signature - Generate HMAC signature

• GET /user/me/stats - Get user statistics

Token Launcher (/token-launcher)

• POST /token-launcher/launch - Launch a GameCoin

• GET /token-launcher/launch/:jobId - Check launch status

Rate Limits

• Default: 60 requests per minute

• Some endpoints may have stricter limits

Error Responses

All errors follow a standard format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Common status codes:

• 400 - Bad Request (validation error)

• 401 - Unauthorized (invalid/missing auth)

• 403 - Forbidden (not allowed)

• 404 - Not Found

• 429 - Too Many Requests (rate limited)

• 500 - Internal Server Error

SDKs

For easier integration, use our official SDKs:

• Vanilla JS SDK - Browser-based games

• Server SDK - Backend integrations

• React Examples - React integration patterns