Wallet Developers

Add Play & Earn anywhere. Reward your users top tokens.

Integrate Open Game Protocol into your wallet to let users discover and play games that reward tokens they hold.

Step 1: Check if a token has games available

Before displaying a "Play & Earn" button, check whether a given token has games with rewards.

API Request Example

async function checkTokenHasGames(tokenAddress: string): Promise<boolean> {
  const response = await fetch(
    'https://api.opengameprotocol.com/games/batch/token-ids',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tokenIds: [tokenAddress] })
    }
  );
  const data = await response.json();
  
  // Response format:
  // {
  //   "tokenAddress123": {
  //     "games": [{ "id": "...", "name": "...", "imageUrl": "..." }],
  //     "total": 2
  //   }
  // }
  return data[tokenAddress]?.total > 0;
}

Implementation Example

const tokenAddress = "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN";

checkTokenHasGames(tokenAddress).then((hasGames) => {
  if (hasGames) {
    console.log("Show 'Play & Earn' button");
    // Update UI to display "Play & Earn" button
  } else {
    console.log("No games available for this token");
  }
});

---

Step 2: Fetch available games for a token

When the "Play & Earn" button is tapped, retrieve the full list of games that reward this token.

API Request Example

interface Game {
  id: string;
  name: string;
  description: string;
  imageUrl: string;
  coverImage?: string;
  gameUrl: string;
  isHTMLGame: boolean;
  iframable: boolean;
  rewardPoolValueUsd?: string;
}

async function listTokenGames(tokenAddress: string): Promise<Game[]> {
  const response = await fetch(
    `https://api.opengameprotocol.com/games/token-id/${tokenAddress}/full`
  );
  const games: Game[] = await response.json();
  
  // Response is an array of full Game objects
  // [
  //   {
  //     "id": "dca7c105-2d37-4dc7-95df-fd22e727b72c",
  //     "name": "Flappy Bird",
  //     "description": "Classic flappy bird game",
  //     "imageUrl": "https://cdn.opengameprotocol.com/...",
  //     "gameUrl": "https://example.com/flappy",
  //     "isHTMLGame": true,
  //     "iframable": true,
  //     "rewardPoolValueUsd": "150.00"
  //   }
  // ]
  return games;
}

Implementation Example

const tokenAddress = "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN";

listTokenGames(tokenAddress).then((games) => {
  if (games.length > 0) {
    console.log("Available games:", games);
    
    // Render list of games for user selection
    games.forEach(game => {
      console.log(`- ${game.name}: ${game.gameUrl}`);
    });
    
    // Or navigate directly to top game
    const topGame = games[0];
    window.open(topGame.gameUrl, '_blank');
  } else {
    console.log("No games available for this token");
  }
});

---

Step 3: Display Games (Optional)

For a richer integration, you can embed the OGP Carousel filtered by token. See the Carousel Integration Guide for details.

<iframe 
  src="https://carousel.opengameprotocol.com?tokenAddress=YOUR_TOKEN_ADDRESS&tokenNetwork=solana"
  width="100%"
  height="600px"
  style="border: none;"
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; fullscreen"
></iframe>

---

Batch Requests

If you need to check multiple tokens at once (e.g., for a user's portfolio), use the batch endpoint:

async function checkMultipleTokens(tokenAddresses: string[]): Promise<Record<string, boolean>> {
  const response = await fetch(
    'https://api.opengameprotocol.com/games/batch/token-ids',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tokenIds: tokenAddresses })
    }
  );
  const data = await response.json();
  
  // Convert to simple hasGames map
  const result: Record<string, boolean> = {};
  for (const tokenId of tokenAddresses) {
    result[tokenId] = data[tokenId]?.total > 0;
  }
  return result;
}

// Example: Check user's portfolio
const portfolio = [
  "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "So11111111111111111111111111111111111111112"
];

checkMultipleTokens(portfolio).then((results) => {
  for (const [token, hasGames] of Object.entries(results)) {
    if (hasGames) {
      console.log(`Token ${token} has games!`);
    }
  }
});

Note: The batch endpoint supports up to 100 token addresses per request.

---

Earn Distribution Fees

Wallets can earn a share of rewards distributed through games. See the Carousel Integration Guide for details on setting up distributor keys.