Market

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

Authentication

Generate HMAC Signature

POST /user/hmac-signature

Generate an HMAC signature for authenticating API requests. This endpoint is used to generate the Authorization header required for protected endpoints.

Request Body:

{
  "secretKey": "your-secret-key",
  "method": "POST",
  "path": "/games",
  "apiKey": "your-api-key"
}

Response:

{
  "data": {
    "signature": "HMAC-SHA256 apiKey=your-api-key signature=abc123... timestamp=1234567890"
  }
}

Example:

async function getSignature(method, path) {
  const response = await fetch('https://api.opengameprotocol.com/user/hmac-signature', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      secretKey: 'your-secret-key',
      method: method,
      path: path,
      apiKey: 'your-api-key',
    }),
  });
  
  const result = await response.json();
  return result.data.signature;
}

---

Games Endpoints

Get All Games

GET /games

Retrieve a list of all games with optional pagination, sorting, and filtering.

Query Parameters:

• limit (optional, default: 50, max: 100) - Number of games to retrieve

• offset (optional, default: 0) - Number of games to skip for pagination

• sort (optional, default: 'desc') - Sort order: asc or desc

• sortBy (optional, default: 'totalRewardsPoolValueUsd') - Field to sort by:

  • totalRewardsAllocatedUsd

  • name

  • createdAt

  • estimatedDailyRewardsUsd

  • totalRewardsPoolValueUsd

• query (optional) - Search query to filter games by name or description

• include_extra (optional, default: false) - Include token association information

Example Request:

curl "https://api.opengameprotocol.com/games?limit=10&offset=0&sortBy=totalRewardsPoolValueUsd&sort=desc"

Example Response:

{
  "games": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Awesome Game",
      "description": "A fun play-to-earn game",
      "gameUrl": "https://example.com/game",
      "imageUrl": "https://cdn.opengameprotocol.com/games/image.png",
      "totalRewardsPoolValueUsd": "15000.50",
      "isHtmlGame": true,
      "hasSdk": true
    }
  ],
  "offset": 0,
  "hasMore": true,
  "total": 158
}

JavaScript Example:

async function getAllGames(limit = 50, offset = 0) {
  const params = new URLSearchParams({
    limit: limit.toString(),
    offset: offset.toString(),
    sortBy: 'totalRewardsPoolValueUsd',
    sort: 'desc'
  });
  
  const response = await fetch(
    `https://api.opengameprotocol.com/games?${params}`
  );
  
  return await response.json();
}

---

Register a New Game

POST /games 🔒

Register a new game on the platform. Requires HMAC authentication.

Headers:

Content-Type: multipart/form-data
x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Form Data Fields:

• name (required) - Game name

• description (required) - Game description

• gameUrl (required) - URL where the game is hosted

• platform (required) - Platform type: WEB, DESKTOP, MOBILE, or CONSOLE

• isHTMLGame (optional) - Whether the game is an HTML5 game

• iframable (optional) - Whether the game can be embedded in an iframe

• image (optional) - Game thumbnail image file

• coverImage (optional) - Game cover image file

• base64Image (optional) - Base64 encoded game image (alternative to file upload)

• base64CoverImage (optional) - Base64 encoded cover image (alternative to file upload)

• twitter (optional) - Twitter/X profile URL

• discord (optional) - Discord server URL

• telegram (optional) - Telegram group URL

• maxScorePerSession (optional) - Maximum points per gaming session

• maxSessionsPerDay (optional) - Maximum number of sessions per day

• maxCumulativePointsPerDay (optional) - Maximum total points per day

• orgRewardsSplit (optional) - Organization rewards split configuration (see detailed explanation below)

• jwksUrl (optional) - JSON Web Key Set URL for authentication

Image Upload (image and coverImage)

Games require at least one image (thumbnail). You can provide images using either file uploads or base64 encoded strings.

Option 1: File Upload (Recommended for larger images)

Upload image files using multipart/form-data:

const formData = new FormData();
formData.append('name', 'My Game');
formData.append('description', 'Game description');
formData.append('gameUrl', 'https://mygame.com');
formData.append('platform', 'WEB');

// Add image file from file input
const imageFile = document.querySelector('#imageInput').files[0];
formData.append('image', imageFile);

// Optionally add cover image
const coverFile = document.querySelector('#coverInput').files[0];
formData.append('coverImage', coverFile);

Option 2: Base64 Encoded Strings (For smaller images or when file upload isn't available)

Provide images as base64 data URIs:

const formData = new FormData();
formData.append('name', 'My Game');
formData.append('description', 'Game description');
formData.append('gameUrl', 'https://mygame.com');
formData.append('platform', 'WEB');

// Base64 encoded image with data URI
formData.append('base64Image', 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...');

// Optionally add base64 cover image
formData.append('base64CoverImage', 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...');

Image Requirements:

• Required: At least one image must be provided (image file OR base64Image string)

• Priority: If both image file and base64Image are provided, the file upload takes precedence

• Formats: jpeg, jpg, png, gif, webp

• Size Limit (Base64): Maximum 5MB per image when using base64 encoding

• Size Limit (File Upload): Check API limits (typically larger than base64)

• Data URI Format: Must be in format data:image/{format};base64,{data}

  • ✅ Valid: data:image/png;base64,iVBORw0KGg...

  • ✅ Valid: data:image/jpeg;base64,/9j/4AAQ...

  • ❌ Invalid: Missing data:image/ prefix

  • ❌ Invalid: Missing ;base64, separator

Example Error Responses:

Missing image:

{
  "statusCode": 400,
  "message": "No image provided",
  "error": "Bad Request"
}

Invalid base64 format:

{
  "statusCode": 400,
  "message": "Invalid base64 image format",
  "error": "Bad Request"
}

Unsupported image format:

{
  "statusCode": 400,
  "message": "Unsupported image format: bmp. Supported formats: jpeg, jpg, png, gif, webp",
  "error": "Bad Request"
}

Image too large:

{
  "statusCode": 400,
  "message": "Image file size exceeds 5MB limit. Please use a smaller image or the UPLOAD flow for larger files.",
  "error": "Bad Request"
}

Organization Rewards Split (orgRewardsSplit)

The orgRewardsSplit field allows you to distribute creator rewards among multiple team members, developers, or partners. This is useful for games developed by studios, teams, or platforms with multiple contributors.

Format:

{
  "userId1": 5000,
  "userId2": 3000,
  "userId3": 2000
}

Key Concepts:

1. Basis Points (BPS): Values are expressed in basis points where 10,000 BPS = 100%

   • 10000 BPS = 100%

   • 5000 BPS = 50%

   • 2500 BPS = 25%

   • 100 BPS = 1%

2. Total Must Equal 10,000: The sum of all basis points must exactly equal 10,000

   • ✅ Valid: { "user1": 6000, "user2": 4000 } (6000 + 4000 = 10000)

   • ❌ Invalid: { "user1": 6000, "user2": 3000 } (6000 + 3000 = 9000, missing 1000)

   • ❌ Invalid: { "user1": 6000, "user2": 5000 } (6000 + 5000 = 11000, exceeds 10000)

3. User Identifiers: Keys can be in the following formats. Important: All identifiers must correspond to users who have logged into OGP via Privy (or will be created automatically):

   • OGP User IDs (UUID format): "550e8400-e29b-41d4-a716-446655440000" - Direct OGP user ID

   • Privy IDs: "did:privy:abc123..." - Full Privy user ID

   • Solana Wallet Addresses: "sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC" or "solana:..." - Wallet linked to a Privy account

   • Ethereum Wallet Addresses: "eth:0x123..." or "ethereum:0x123..." - Wallet linked to a Privy account

   • Email Addresses: "email:[email protected]" - Email linked to a Privy account

4. Important User Requirements:

   • For wallet/email identifiers: The user must have previously logged into OGP using Privy with that wallet or email, OR the system will automatically create a Privy user for them

   • For OGP User IDs: Must be an existing user in the OGP system

   • For Privy IDs: Must be a valid Privy user ID

   • All team members will receive their split of creator rewards automatically when the game generates revenue

5. Ownership Verification:

   • If you don't own the game domain (verified via API key meta tag), the orgRewardsSplit will be overridden to 100% to you

   • To use custom splits, you must first claim ownership by adding the verification meta tag to your game

6. Default Behavior: If not provided or empty, defaults to 100% (10000 BPS) to the game creator

Example: Equal Split Between 3 Developers

{
  "orgRewardsSplit": {
    "550e8400-e29b-41d4-a716-446655440000": 3333,
    "did:privy:abc123def456": 3333,
    "sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC": 3334
  }
}

Example: Studio + Developer Split (70% / 30%)

{
  "orgRewardsSplit": {
    "studio-user-id": 7000,
    "developer-user-id": 3000
  }
}

Example: Publisher Platform + 5 Game Developers

{
  "orgRewardsSplit": {
    "platform-publisher-id": 5000,
    "game-dev-1": 1000,
    "game-dev-2": 1000,
    "game-dev-3": 1000,
    "game-dev-4": 1000,
    "game-dev-5": 1000
  }
}

Common Use Cases:

• Game Studios: Split rewards between studio owner and developers

• Publishing Platforms: Take a platform fee and distribute remainder to game creators

• Collaborative Projects: Fairly distribute rewards among team members

• Outsourced Development: Pay developers and contractors from game rewards

• Multi-Team Games: Split between art, programming, and design teams

Error Responses:

Invalid split (doesn't sum to 10000):

{
  "statusCode": 400,
  "message": "Total org rewards split must equal 10000 bps",
  "error": "Bad Request"
}

Split exceeds 10000:

{
  "statusCode": 400,
  "message": "Total org rewards split exceeds 10000 bps",
  "error": "Bad Request"
}

Invalid user identifier:

{
  "statusCode": 400,
  "message": "Unable to resolve playerId: invalid-id",
  "error": "Bad Request"
}

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Awesome Game",
  "description": "A fantastic play-to-earn experience",
  "gameUrl": "https://mygame.com",
  "imageUrl": "https://cdn.opengameprotocol.com/games/550e8400.png",
  "createdAt": "2025-11-28T12:00:00.000Z"
}

Full JavaScript Example:

See register-game-example.md for a complete implementation.

Example with orgRewardsSplit:

async function registerGameWithTeamSplit(gameData) {
  const signature = await getSignature('POST', '/games');
  
  const formData = new FormData();
  formData.append('name', gameData.name);
  formData.append('description', gameData.description);
  formData.append('gameUrl', gameData.gameUrl);
  formData.append('platform', 'WEB');
  formData.append('isHTMLGame', 'true');
  
  // Add image file
  if (gameData.imageFile) {
    formData.append('image', gameData.imageFile);
  }
  
  // Define team split: 50% studio, 30% lead dev, 20% artist
  const teamSplit = {
    'studio-user-id-uuid': 5000,  // 50%
    'lead-dev-user-id-uuid': 3000, // 30%
    'artist-user-id-uuid': 2000    // 20%
  };
  
  // Important: FormData requires JSON string for objects
  formData.append('orgRewardsSplit', JSON.stringify(teamSplit));
  
  const response = await fetch(
    'https://api.opengameprotocol.com/games',
    {
      method: 'POST',
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
      body: formData,
    }
  );
  
  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Registration failed: ${response.status} - ${errorText}`);
  }
  
  return await response.json();
}

// Usage example
const gameData = {
  name: 'Team Adventure Game',
  description: 'An epic adventure created by our studio',
  gameUrl: 'https://teamgame.com',
  imageFile: imageBlob, // File or Blob object
};

try {
  const result = await registerGameWithTeamSplit(gameData);
  console.log('Game registered successfully:', result);
  console.log('Rewards will be split among team members automatically');
} catch (error) {
  console.error('Failed to register game:', error.message);
}

---

Update an Existing Game

POST /games/update/{gameId} 🔒

Update an existing game's metadata and images. Requires HMAC authentication.

Path Parameters:

• gameId (required) - UUID of the game to update

Headers & Form Data: Same as Register Game endpoint.

Example:

async function updateGame(gameId, updates) {
  const signature = await getSignature('POST', `/games/update/${gameId}`);
  
  const formData = new FormData();
  formData.append('name', updates.name);
  formData.append('description', updates.description);
  formData.append('gameUrl', updates.gameUrl);
  formData.append('platform', updates.platform);
  
  if (updates.imageFile) {
    formData.append('image', updates.imageFile);
  }
  
  const response = await fetch(
    `https://api.opengameprotocol.com/games/update/${gameId}`,
    {
      method: 'POST',
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
      body: formData,
    }
  );
  
  return await response.json();
}

---

Get Game by ID

GET /games/id/{id}

Retrieve detailed information about a specific game.

Path Parameters:

• id (required) - UUID of the game

Query Parameters:

• include_tokens (optional, default: false) - Include associated token information

Example Request:

curl "https://api.opengameprotocol.com/games/id/550e8400-e29b-41d4-a716-446655440000?include_tokens=true"

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Awesome Game",
  "description": "A fun play-to-earn game",
  "gameUrl": "https://example.com/game",
  "imageUrl": "https://cdn.opengameprotocol.com/games/image.png",
  "coverImage": "https://cdn.opengameprotocol.com/games/cover.png",
  "isHtmlGame": true,
  "iframable": true,
  "platform": "WEB",
  "twitter": "https://twitter.com/awesomegame",
  "discord": "https://discord.gg/awesomegame",
  "totalRewardsPoolValueUsd": "15000.50",
  "totalRewardsAllocatedUsd": "5000.25",
  "tokens": [
    {
      "address": "TokenMint123...",
      "symbol": "GAME",
      "name": "Game Token",
      "imageUrl": "https://cdn.opengameprotocol.com/tokens/game.png"
    }
  ]
}

JavaScript Example:

async function getGameById(gameId, includeTokens = false) {
  const params = includeTokens ? '?include_tokens=true' : '';
  const response = await fetch(
    `https://api.opengameprotocol.com/games/id/${gameId}${params}`
  );
  return await response.json();
}

---

Get My Games

GET /games/me 🔒

Retrieve games created by the authenticated user. Requires HMAC authentication.

Headers:

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

Query Parameters:

• limit (optional, default: 50) - Number of games to retrieve

• offset (optional, default: 0) - Number of games to skip

• sort (optional, default: 'desc') - Sort order: asc or desc

• include_extra (optional, default: false) - Include additional game information

Example Request:

async function getMyGames(limit = 50, offset = 0) {
  const signature = await getSignature('GET', '/games/me');
  
  const params = new URLSearchParams({
    limit: limit.toString(),
    offset: offset.toString(),
    sort: 'desc'
  });
  
  const response = await fetch(
    `https://api.opengameprotocol.com/games/me?${params}`,
    {
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
    }
  );
  
  return await response.json();
}

Example Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Game 1",
    "description": "First game",
    "gameUrl": "https://game1.com",
    "imageUrl": "https://cdn.opengameprotocol.com/games/game1.png",
    "totalRewardsPoolValueUsd": "10000.00"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "My Game 2",
    "description": "Second game",
    "gameUrl": "https://game2.com",
    "imageUrl": "https://cdn.opengameprotocol.com/games/game2.png",
    "totalRewardsPoolValueUsd": "5000.00"
  }
]

---

Toggle Game Visibility

POST /games/toggle-visibility/{id} 🔒

Toggle the visibility of a game (show/hide from public listings). Requires HMAC authentication and game ownership.

Path Parameters:

• id (required) - UUID of the game

Headers:

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

Example Request:

async function toggleGameVisibility(gameId) {
  const signature = await getSignature('POST', `/games/toggle-visibility/${gameId}`);
  
  const response = await fetch(
    `https://api.opengameprotocol.com/games/toggle-visibility/${gameId}`,
    {
      method: 'POST',
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
    }
  );
  
  return await response.json();
}

Example Response:

{
  "success": true,
  "message": "Game visibility toggled successfully",
  "game": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Game",
    "hidden": true
  }
}

---

Claim Game Ownership

POST /games/claim-ownership/{gameId} 🔒

Claim ownership of a game by verifying control of the game's domain. Requires HMAC authentication.

Path Parameters:

• gameId (required) - UUID of the game to claim

Headers:

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

How it works:

1. The game creator must add a verification meta tag to their game's HTML

2. The verification tag contains the user's API key

3. This endpoint verifies the tag exists and matches the authenticated user

Example Request:

async function claimGameOwnership(gameId) {
  const signature = await getSignature('POST', `/games/claim-ownership/${gameId}`);
  
  const response = await fetch(
    `https://api.opengameprotocol.com/games/claim-ownership/${gameId}`,
    {
      method: 'POST',
      headers: {
        'x-auth-provider': 'hmac',
        'Authorization': signature,
      },
    }
  );
  
  return await response.json();
}

Verification Meta Tag: Add this to your game's HTML <head> section:

<meta name="ogp-api-key" content="your-api-key-here">

Example Response:

{
  "success": true,
  "message": "Game ownership claimed successfully",
  "game": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "ownerId": "user-id-123",
    "ownershipValidated": true
  }
}

---

Batch Operations

Get Games by Token IDs

POST /games/batch/token-ids

Retrieve games associated with multiple token addresses in a single request. Maximum 100 token IDs per request.

Request Body:

{
  "tokenIds": [
    "TokenMintAddress1...",
    "TokenMintAddress2...",
    "TokenMintAddress3..."
  ]
}

Example Response:

{
  "TokenMintAddress1...": {
    "games": [
      {
        "id": "game-id-1",
        "imageUrl": "https://cdn.opengameprotocol.com/games/game1.png",
        "name": "Game One"
      },
      {
        "id": "game-id-2",
        "imageUrl": "https://cdn.opengameprotocol.com/games/game2.png",
        "name": "Game Two"
      }
    ],
    "total": 2
  },
  "TokenMintAddress2...": {
    "games": [
      {
        "id": "game-id-3",
        "imageUrl": "https://cdn.opengameprotocol.com/games/game3.png",
        "name": "Game Three"
      }
    ],
    "total": 1
  }
}

JavaScript Example:

async function getGamesByTokenIds(tokenIds) {
  const response = await fetch(
    'https://api.opengameprotocol.com/games/batch/token-ids',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tokenIds }),
    }
  );
  
  return await response.json();
}

---

Get Games by Game IDs

POST /games/batch/ids

Retrieve multiple games by their IDs in a single request. Maximum 100 game IDs per request.

Request Body:

{
  "gameIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

Example Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Game One",
    "description": "First game",
    "gameUrl": "https://game1.com",
    "imageUrl": "https://cdn.opengameprotocol.com/games/game1.png",
    "isHtmlGame": true
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Game Two",
    "description": "Second game",
    "gameUrl": "https://game2.com",
    "imageUrl": "https://cdn.opengameprotocol.com/games/game2.png",
    "isHtmlGame": true
  }
]

JavaScript Example:

async function getGamesByIds(gameIds) {
  const response = await fetch(
    'https://api.opengameprotocol.com/games/batch/ids',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ gameIds }),
    }
  );
  
  return await response.json();
}

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request:

{
  "statusCode": 400,
  "message": "Invalid request parameters",
  "error": "Bad Request"
}

401 Unauthorized:

{
  "statusCode": 401,
  "message": "Invalid or missing authentication",
  "error": "Unauthorized"
}

403 Forbidden:

{
  "statusCode": 403,
  "message": "You do not have permission to perform this action",
  "error": "Forbidden"
}

404 Not Found:

{
  "statusCode": 404,
  "message": "Game not found",
  "error": "Not Found"
}

500 Internal Server Error:

{
  "statusCode": 500,
  "message": "An error occurred while processing your request",
  "error": "Internal Server Error"
}

---

Rate Limits

The API implements rate limiting to ensure fair usage:

• Default Rate Limit: 60 requests per minute per IP address

• Authenticated Endpoints: May have higher limits based on your account

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "statusCode": 429,
  "message": "Too many requests, please try again later",
  "error": "Too Many Requests"
}

---

Best Practices

1. Cache Responses: Cache game data locally to reduce API calls

2. Use Batch Endpoints: When fetching multiple games, use batch endpoints instead of individual requests

3. Handle Errors Gracefully: Always implement proper error handling