Dev Save Points Example

Saving Player Points with devBatchSavePoints

Once you've registered your game and obtained a gameApiKey, you can save player points to the play.fun platform. Like other protected endpoints, this request requires an HMAC signature. See API Reference - Authentication for the full signing spec.

The devBatchSavePoints endpoint lets you batch save player points in the context of your game. At minimum, you must provide:

• gameApiKey – Your game owner/creator API key (UUID).

• points – An array of objects containing a playerId and points value.

Player ID Formats

The playerId field accepts multiple formats:

Format	Example	Description
Solana wallet	sol:9qdvVLY3v...	Looks up/creates user by Solana address
Ethereum wallet	eth:0x123...	Looks up/creates user by ETH address
Email	email:[email protected]	Looks up/creates user by email
Twitter/X	twitter:username or x:username	Looks up/creates user by Twitter/X handle
Privy ID	did:privy:abc123	Direct Privy user ID
OGP User ID (UUID)	550e8400-e29b-41d4-...	Raw internal user ID (fastest)

Understanding the playerIdToOgpId Response

Every successful response includes a playerIdToOgpId object that maps each input identifier you sent to the player's internal OGP user UUID:

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

Why this matters: When you use identifiers like sol: or email:, the server must resolve them to an internal user on every request. This adds latency and external API calls. By caching the returned OGP UUIDs and using them directly in future requests, you skip that resolution entirely.

Note that if a raw OGP UUID is passed, it maps to itself (no resolution needed). This is the fastest path — always prefer using cached OGP UUIDs for repeat players.

JavaScript Example

const API_KEY = 'your-api-key';
const SECRET_KEY = 'your-secret-key';

/**
 * Generates HMAC signature for API authentication
 * @returns {Promise<string>} The full Authorization header value
 */
async function getAuthHeader(method, path) {
  const response = await fetch('https://api.play.fun/user/hmac-signature', {
    method: 'POST',
    body: JSON.stringify({
      secretKey: SECRET_KEY,
      path,
      method,
      apiKey: API_KEY,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    throw new Error(`Failed to get signature: ${response.status} ${response.statusText}`);
  }

  const result = await response.json();
  const signature = result.data.signature;
  const timestamp = Date.now();
  return `HMAC-SHA256 apiKey=${API_KEY}, signature=${signature}, timestamp=${timestamp}`;
}

/**
 * Saves player points for a game
 * @param {string} gameApiKey - API key (UUID) of the game owner/creator
 * @param {Array<{playerId: string, points: string}>} points - Array of player points
 * @returns {Promise<Object>} API response with savedCount and playerIdToOgpId mapping
 */
async function savePlayerPoints(gameApiKey, points) {
  const authHeader = await getAuthHeader('POST', '/play/dev/batch-save-points');

  const payload = {
    gameApiKey,
    points,
  };

  console.log('Submitting player points:', payload);

  const response = await fetch('https://api.play.fun/play/dev/batch-save-points', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      'x-auth-provider': 'hmac',
      Authorization: authHeader,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Save points failed: ${response.status} ${response.statusText} - ${errorText}`);
  }

  const result = await response.json();
  console.log('Save points response:', result);
  return result;
}

// Example usage with different identifier formats:
const result = await savePlayerPoints('YOUR_GAME_API_KEY', [
  // By Solana wallet address
  { playerId: 'sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC', points: '100' },
  // By email
  { playerId: 'email:[email protected]', points: '250' },
  // By Twitter/X handle
  { playerId: 'twitter:elonmusk', points: '150' },
  // By raw OGP User ID (fastest - no resolution needed)
  { playerId: '550e8400-e29b-41d4-a716-446655440000', points: '500' },
]);

// Cache the mapping for future requests
const playerMappings = result.playerIdToOgpId;
// e.g. { "sol:9qdvVLY3v...": "a1b2c3d4-...", "email:[email protected]": "e5f6g7h8-..." }

// On subsequent requests, use the OGP UUIDs directly — no resolution overhead:
const nextResult = await savePlayerPoints('YOUR_GAME_API_KEY', [
  { playerId: playerMappings['sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC'], points: '200' },
  { playerId: playerMappings['email:[email protected]'], points: '300' },
]);

Using the Server SDK

If you're using Node.js, the @playdotfun/server-sdk handles HMAC signing automatically:

import { OpenGameClient } from '@playdotfun/server-sdk';

const ogp = new OpenGameClient({
  apiKey: 'your-api-key',
  secretKey: 'your-secret-key',
});

// Single player
await ogp.play.savePoints({
  gameId: 'your-game-uuid',
  playerId: 'sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC',
  points: 100,
});

// Batch save
const result = await ogp.play.batchSavePoints({
  gameId: 'your-game-uuid',
  pointsRecord: {
    'sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC': 100,
    'email:[email protected]': 250,
  },
});