Open Game Endpoints

Introduction

Most integration can be done via the frontend Open Game SDK. However, for more advanced server side integration, below is a list of endpoints at https://api.opengameprotocol.com/

Before using the endpoints, see Game developer onboarding

Endpoints

/game/getSessionToken

Method: GET
Query Parameters
- playerId (string, required): The player ID of the current player.
- gameApiKey (string, required): The game’s public API key.
- gameId (string, required): The unique game id for your game.
Status: 200 OK
Response (application/json)
- token (string): Session token for subsequent requests.

Example

curl 'https://api.opengameprotocol.com/game/getSessionToken?playerId=examplePlayer&apiKey=yourApiKey&gameId=yourGameId'

/game/listPlayerRewards

Method: GET
Query Parameters:
- playerId (string, required): The player ID.
- network (string, required): Blockchain network (e.g., "solana").
Status: 200 OK
Response (application/json)
- rewardDetails (array): List of reward details.
  - id (string)
  - name (string)
  - image (string)
  - description (string)
  - points (number)
  - rewards (array):
    token (object): { address, symbol, name, image, network, history (array of { date, points, amount, gAmount, mUsdAmount, gUsdAmount }) }
- totalUsd (number): Total USD value.
- topTokenNames (array): Top token names.

Example

curl 'https://api.opengameprotocol.com/game/listPlayerRewards?playerId=examplePlayer&network=solana'

/game/listCreatorRewards

Method: GET
Query Parameters:
- creatorId (string, required): The creator ID.
- network (string, required): Blockchain network (e.g., "solana").
Status: 200 OK
Response (application/json)
- rewardDetails (array): List of reward details.
  - name (string)
  - symbol (string)
  - image (string)
  - usdAmount (number)
  - unclaimed (number)
  - address (string)
  - network (string)
- totalUsd (number): Total USD value.
- topTokenNames (array): Top token names.

Example

curl 'https://api.opengameprotocol.com/game/listCreatorRewards?creatorId=exampleCreator&network=solana'

/game/claimRewards

Method: POST
Header:
- x-auth-provider (string, required): privy or hmac
- Authorization (string, required): JWT or HMAC signature
Body (application/json)
- network (string, required): Blockchain network (e.g., "solana").
- gTokenAddress (string, required): The gToken address for rewards.
- walletAddress (string, required): The user's wallet address.
- blockhash (string, required): The recent blockhash for the transaction.
- claimType (string, optional): "player" or "creator" (defaults to "player").
Status: 200 OK
Response (application/json)
- tx (string): The transaction payload to sign and send.
- txId (string): The transaction ID for tracking.

Example

curl -X POST 'https://api.opengameprotocol.com/game/claimRewards' 
    -H 'x-auth-provider: privy' 
    -H 'Content-Type: application/json' 
    -d '{
    "network": "solana",
    "gTokenAddress": "exampleGToken",
    "walletAddress": "exampleWallet",
    "blockhash": "exampleBlockhash",
    "claimType": "player"
}'

/game/savePoints

Parameters

Method: POST
Header:
- x-auth-provider (string, required): privy or hmac
- Authorization (string, required): JWT or HMAC signature
Body (application/json)
- points (number or string, required): Daily points to save for the user (BigIntString).
- context (object, optional): Contextual token info.
- network (string): e.g., "solana".
- tokenAddress (string): The token address for contextual points.
Status: 200 OK
Response (application/json)
- totalPoints (string): The updated total points (BigIntString).

Example

curl -X POST 'https://api.opengameprotocol.com/game/savePoints' 
    -H 'x-auth-provider: player' 
    -H 'Content-Type: application/json' 
    -d '{
    "points": "25",
    "context": {"network": "solana", "tokenAddress": "exampleToken"}
}'

/game/getPoints

Parameters

Method: GET
Header:
- x-auth-provider (string, required): Authentication provider (privy or hmac)
Query Parameters:
- tokenAddress (string, optional): Filter by token address.
- network (string, optional): Filter by network (e.g., "solana").
Status: 200 OK
Response (application/json):
- points (string): Total points (BigIntString).
- tokens (array): Breakdown by tokens (top 3, including those with 0 points).
  - name (string)
  - image (string)
  - symbol (string)
  - network (string)
  - address (string)
  - points (string, optional): Points for this token (BigIntString).

Example

curl 'https://api.opengameprotocol.com/game/getPoints?tokenAddress=exampleToken&network=solana' 
-H 'x-auth-provider: player'

/game/getClaimStatus

Parameters

Method: GET
Query Parameters:
- txHash (string, required): Transaction hash from claiming rewards.
Header:
- x-auth-provider (string, required): Authentication provider (only "privy" supported).
Status: 200 OK
Response (application/json):
- status (string): Claim status ("in-progress", "completed", or "failed").

/game/getTimeUntilNextClaim

Method: GET
Parameters: None
Status: 200 OK
Response (application/json):
- time (integer): Time until the next daily claim (in seconds, presumably).

/market/getSignature

Method
- POST
Headers
- Content-Type: application/json
Body (application/json)
- secretKey (string, required): Your OGP secret key
- apiKey (string, required): Your public API key
- path (string, required): API path being accessed (e.g., /market/registerGame)
- method (string, required): HTTP method of the request (e.g., post)
Status
- 200 OK
Response (application/json):
- signature (string): HMAC signature to use in authenticated requests

Example

curl -X POST 'https://api.opengameprotocol.com/market/getSignature' \
  -H 'Content-Type: application/json' \
  -d '{
    "secretKey": "your-secret-key",
    "apiKey": "your-api-key",
    "path": "/market/registerGame",
    "method": "post"
  }'

/market/registerGame

Method
- POST
Header:
- x‑auth‑provider (string, required): Authentication provider — "privy" or "hmac".
- Authorization (string, required):
  - When x‑auth‑provider: privy → Bearer <PRIVY_JWT>
  - When x‑auth‑provider: hmac → an HMAC signature generated with /market/getSignature.
Body (application/json):
- name (string, required): Name of the game.
- description (string, required): Description of the game.
- image (string, required): Base‑64 string. Main icon for the game
- coverImage (string, optional): Base‑64 string. Optional cover image for the game.
- gameUrl (string, required): Public URL where the game can be played.
- platform (string enum (web, ios, android), required): Platform type (e.g., "web").
- isHTMLGame (boolean, required): Whether the game is an HTML game.
- twitter, discord, telegram (string, optional): Social links.
- developer (object, optional): Used when the logged-in developer is registering their own game.
  - token (string): A valid Privy JWT token for the developer.
  - rewardPercentage (integer 0-100): Percentage of reward allocated to this developer.
- developers (array, optional): Used when a publisher registers on behalf of other developers.
  - id (string): The developer’s user Id.
  - rewardPercentage (integer 0-100): Percentage of reward allocated to this developer.
- tokens (array, optional): List of existing token associations with the game. Each token object contains:
  - address (string, required): Token address
  - network (string, required): "solana"
Status:
- 200 OK
Response (application/json):
- gameApiKey (string): API key for the newly‑created game

Demo Project

See, the game-registration demo at https://github.com/StoryverseCo/ogp-demos/

Example: Single Developer

curl -X POST 'https://api.opengameprotocol.com/market/registerGame' \
  -H 'accept: application/json' \
  -H 'x-auth-provider: privy' \
  -H 'Authorization: Bearer YOUR_PRIVY_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Super Foo",
    "description": "Endless‑runner on chain",
    "image": "https://cdn.example.com/foo.png",
    "gameUrl": "https://foo.com/",
    "platform": "web",
    "isHTMLGame": true,
    "developer": {
      "token": "YOUR_PRIVY_JWT",
      "rewardPercentage": 100
    }
  }'

Example: Multiple Developers (HMAC flow)

// 1) Get signature
const { data: { signature } } = await fetch(`${BASE}/market/getSignature`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secretKey: SECRET_KEY,
    path: '/market/registerGame',
    method: 'post',
    apiKey: API_KEY
  })
});

// 2) Call registerGame
await fetch(`${BASE}/market/registerGame`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-provider': 'hmac',
    Authorization: signature
  },
  body: JSON.stringify({
    name: 'Super Foo',
    image: 'your-base-64-string',
    coverImage: 'your-base-64-string',
    gameUrl: 'https://foo.com/',
    platform: 'web',
    isHTMLGame: true,
    developers: [
      { id: 'OGP_USER_KEY_A', rewardPercentage: 70 },
      { id: 'OGP_USER_KEY_B', rewardPercentage: 30 }
    ],
    tokens: [
      { address: 'TOKEN_ADDRESS', network: 'solana' }
    ]
  })
});

/market/updateGame

Method:
- POST
Header:
- x‑auth‑provider (string, required): Authentication provider — "privy" or "hmac".
- Authorization (string, required):
  - When x‑auth‑provider: privy → Bearer <PRIVY_JWT>
  - When x‑auth‑provider: hmac → an HMAC signature generated with /market/getSignature.
Body (application/json):
- gameApiKey (string, required): API key of the game to update.
- name (string, optional): New name for the game.
- description (string, optional): New description for the game.
- image (string, optional): . Main icon for the game.
- coverImage (string, optional): Base‑64 string. Optional cover image for the game.
- gameUrl (string, optional): New public URL where the game can be played.
- platform (string enum, optional): Platform type - "web", "ios", or "android".
- isHTMLGame (boolean, optional): Whether the game is an HTML game.
- developer (object, optional): Used when the logged-in developer is registering their own game.
  - token (string): A valid Privy JWT token for the developer.
  - rewardPercentage (integer 0-100): Percentage of reward allocated to this developer.
- developers (array, optional): Used when a publisher registers on behalf of other developers.
  - id (string): The developer's user ID.
  - rewardPercentage (integer 0-100): Percentage of reward allocated to this developer.
- twitter, discord, telegram (string, optional): Social links.
- tokens (array, optional): List of existing token associations with the game.
  - If provided: Replaces all existing token associations
  - If empty array ([]): Preserves existing associations (no change)
  - If undefined: No change to existing associations
  Each token object contains:
  - address (string, required): Token address
  - network (string, required): "solana"
Status:
- 200 OK
Response (application/json):
- gameApiKey (string): API key for the newly‑created game

PreviousOpen Game SDK

Last updated 2 months ago