Game

API Reference: https://api.opengameprotocol.com/api-reference

Authentication

For developer endpoints (🔒), you need HMAC authentication. See Games Management - Authentication for details on generating signatures.

---

Play Endpoints

Batch Save Points

POST /play/dev/batch-save-points 🔒

Save points for multiple players in a single request. This is the recommended way to update player scores from your game backend.

Headers:

Content-Type: application/json
x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Request Body:

{
  "gameApiKey": "your-game-owner-id",
  "points": [
    {
      "playerId": "sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC",
      "points": "1500"
    },
    {
      "playerId": "email:[email protected]",
      "points": "2300"
    },
    {
      "playerId": "550e8400-e29b-41d4-a716-446655440000",
      "points": "500"
    }
  ]
}

Player ID Formats:

• Solana Wallet: "sol:9qdvVLY..." or "solana:9qdvVLY..."

• Ethereum Wallet: "eth:0x123..." or "ethereum:0x123..."

• Email: "email:[email protected]"

• Privy ID: "did:privy:abc123..."

• OGP User ID: "550e8400-e29b-41d4-a716-446655440000" (raw UUID)

Response:

{
  "savedCount": 3,
  "playerIdToOgpId": {
    "sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC": "a1b2c3d4-...",
    "email:[email protected]": "e5f6g7h8-...",
    "550e8400-e29b-41d4-a716-446655440000": "550e8400-..."
  },
  "message": "For higher throughput on existing players, please store and use the known playerId => ogpId mappings in subsequent requests."
}

JavaScript Example:

async function savePlayerScores(scores) {
  // Generate HMAC signature for authentication
  const signature = await getSignature('POST', '/play/dev/batch-save-points');
  
  const response = await fetch(
    'https://api.opengameprotocol.com/play/dev/batch-save-points',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
      body: JSON.stringify({
        gameApiKey: 'your-game-owner-id',
        points: scores.map(score => ({
          playerId: score.walletAddress 
            ? `sol:${score.walletAddress}`
            : score.ogpId,
          points: score.points.toString(),
        })),
      }),
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to save points: ${response.status}`);
  }
  
  return await response.json();
}

// Usage
await savePlayerScores([
  { walletAddress: '9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC', points: 1500 },
  { ogpId: '550e8400-e29b-41d4-a716-446655440000', points: 2300 },
]);

Notes:

• Points are cumulative - they add to existing points for the day

• Users are automatically created if they don't exist (via Privy)

• Cache the playerIdToOgpId mapping for better performance on subsequent requests

• Only the game owner/creator can save points

---

Get Player Points

GET /play/dev/points 🔒

Retrieve the current day's points for a specific player in your game.

Headers:

x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Query Parameters:

• gameId (required) - Your game's UUID

• playerId (required) - Player identifier (same formats as batch-save-points)

Example Request:

curl "https://api.opengameprotocol.com/play/dev/points?gameId=c8d75cec-d66f-46df-b0eb-e2065e7ccea3&playerId=sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC" \
  -H "x-auth-provider: hmac" \
  -H "Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=..."

Response:

{
  "points": "1500",
  "ogpId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

JavaScript Example:

async function getPlayerPoints(gameId, playerId) {
  const signature = await getSignature('GET', '/play/dev/points');
  
  const params = new URLSearchParams({
    gameId,
    playerId,
  });
  
  const response = await fetch(
    `https://api.opengameprotocol.com/play/dev/points?${params}`,
    {
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to get points: ${response.status}`);
  }
  
  return await response.json();
}

// Usage
const result = await getPlayerPoints(
  'c8d75cec-d66f-46df-b0eb-e2065e7ccea3',
  'sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC'
);
console.log(`Player has ${result.points} points today`);

---

Get Game Leaderboard

GET /play/dev/leaderboard/{gameId} 🔒

Retrieve the leaderboard for your game. Returns top players ranked by points.

Headers:

x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Path Parameters:

• gameId (required) - Your game's UUID

Query Parameters:

• limit (optional, default: 10) - Number of entries to return

• date (optional, default: today) - Date in YYYY-MM-DD format

Example Request:

curl "https://api.opengameprotocol.com/play/dev/leaderboard/c8d75cec-d66f-46df-b0eb-e2065e7ccea3?limit=100&date=2025-11-28" \
  -H "x-auth-provider: hmac" \
  -H "Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=..."

Response:

[
  {
    "ogpId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "points": "15000"
  },
  {
    "ogpId": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
    "points": "12500"
  },
  {
    "ogpId": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
    "points": "10000"
  }
]

JavaScript Example:

async function getLeaderboard(gameId, limit = 100, date = null) {
  const signature = await getSignature('GET', `/play/dev/leaderboard/${gameId}`);
  
  const params = new URLSearchParams({ limit: limit.toString() });
  if (date) {
    params.append('date', date);
  }
  
  const response = await fetch(
    `https://api.opengameprotocol.com/play/dev/leaderboard/${gameId}?${params}`,
    {
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to get leaderboard: ${response.status}`);
  }
  
  return await response.json();
}

// Usage - Get today's top 100 players
const leaderboard = await getLeaderboard(
  'c8d75cec-d66f-46df-b0eb-e2065e7ccea3',
  100
);

// Get historical leaderboard
const yesterdayLeaderboard = await getLeaderboard(
  'c8d75cec-d66f-46df-b0eb-e2065e7ccea3',
  50,
  '2025-11-27'
);

Notes:

• Leaderboards are calculated per day

• Only shows PLAYER type points (not referrer/distributor points)

• Returns OGP user IDs - you may need to resolve these to player identifiers

• Only the game owner/creator can access leaderboards

---

Rewards Endpoints

Get Game Rewards Pool

GET /rewards/game-rewards-pool/{gameId}

Get the total rewards pool value and breakdown by token for a specific game.

Path Parameters:

• gameId (required) - Game UUID

Example Request:

curl "https://api.opengameprotocol.com/rewards/game-rewards-pool/c8d75cec-d66f-46df-b0eb-e2065e7ccea3"

Response:

{
  "gameId": "c8d75cec-d66f-46df-b0eb-e2065e7ccea3",
  "totalRewardsPoolValueUsd": "15420.50",
  "rewardsByToken": [
    {
      "tokenMint": "So11111111111111111111111111111111111111112",
      "tokenSymbol": "SOL",
      "tokenName": "Solana",
      "rewardsPoolValueUsd": "8500.00",
      "rewardsPoolTokenAmount": "50.5"
    },
    {
      "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "tokenSymbol": "USDC",
      "rewardsPoolValueUsd": "6920.50",
      "rewardsPoolTokenAmount": "6920.50"
    }
  ]
}

JavaScript Example:

async function getGameRewardsPool(gameId) {
  const response = await fetch(
    `https://api.opengameprotocol.com/rewards/game-rewards-pool/${gameId}`
  );
  
  if (!response.ok) {
    throw new Error(`Failed to get rewards pool: ${response.status}`);
  }
  
  return await response.json();
}

// Usage
const pool = await getGameRewardsPool('c8d75cec-d66f-46df-b0eb-e2065e7ccea3');
console.log(`Total rewards pool: $${pool.totalRewardsPoolValueUsd}`);
pool.rewardsByToken.forEach(token => {
  console.log(`${token.tokenSymbol}: $${token.rewardsPoolValueUsd}`);
});

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request:

{
  "statusCode": 400,
  "message": "Invalid game ID",
  "error": "Bad Request"
}

401 Unauthorized:

{
  "statusCode": 401,
  "message": "Invalid HMAC signature",
  "error": "Unauthorized"
}

403 Forbidden:

{
  "statusCode": 403,
  "message": "Only the game owner or creator can perform this action",
  "error": "Forbidden"
}

500 Internal Server Error:

{
  "statusCode": 500,
  "message": "Error adding points",
  "error": "Internal Server Error"
}