API Reference

The play.fun API provides endpoints for game management, player points, rewards, and token operations.

Live API Documentation

Interactive Swagger UI: https://api.play.fun/api-reference

OpenAPI JSON (for AI agents): https://api.play.fun/api-reference-json

The Swagger documentation is auto-generated from the API source code and always reflects the current implementation. Use it to:

• Explore all available endpoints

• See request/response schemas

• Test endpoints directly in the browser

• Feed the OpenAPI JSON to AI agents for automated integration

Authentication

HMAC Authentication

Most developer-facing endpoints require HMAC-SHA256 authentication. Include the following header:

Authorization: HMAC-SHA256 apiKey=<your-api-key>, signature=<hmac-signature>, timestamp=<unix-timestamp>

Also include:

x-auth-provider: hmac

Components:

• apiKey - Your user API key (UUID, from dashboard)

• signature - HMAC-SHA256 of method + "\n" + path + "\n" + timestamp using your secret key

• timestamp - Unix timestamp in milliseconds (must be within 5 minutes of server time)

Important: The method and path are lowercased before signing, and are joined with newline characters (\n).

Generate Signature (Node.js):

import { createHmac } from 'crypto';

function generateSignature(
  method: string,
  path: string,
  timestamp: number,
  secretKey: string,
): string {
  const dataToSign = [method.toLowerCase(), path.toLowerCase(), timestamp].join('\n');

  return createHmac('sha256', secretKey).update(dataToSign).digest('hex');
}

function getAuthHeader(apiKey: string, method: string, path: string, secretKey: string): string {
  const timestamp = Date.now();
  const signature = generateSignature(method, path, timestamp, secretKey);
  return `HMAC-SHA256 apiKey=${apiKey}, signature=${signature}, timestamp=${timestamp}`;
}

// Example usage
const authHeader = getAuthHeader(
  'your-api-key',
  'POST',
  '/play/dev/batch-save-points',
  'your-secret-key',
);

Or use the helper endpoint:

const response = await fetch('https://api.play.fun/user/hmac-signature', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
    method: 'POST',
    path: '/play/dev/batch-save-points',
  }),
});

const result = await response.json();
const signature = result.data.signature;
// Then build the Authorization header yourself:
// `HMAC-SHA256 apiKey=${apiKey}, signature=${signature}, timestamp=${Date.now()}`

Player Authentication

For SDK/player endpoints, use session tokens obtained via the SDK initialization flow.

Main Endpoint Categories

Games (/games)

• GET /games - List all games with pagination and sorting

• POST /games - Register a new game (multipart form-data)

• POST /games/update/:gameId - Update a game

• GET /games/id/:id - Get game by ID

• GET /games/me - Get your games

• POST /games/batch/ids - Get games by game IDs (batch)

• POST /games/batch/token-ids - Get games by token addresses (batch)

• GET /games/token-id/:tokenId/full - Get full games for a token

Play — Dev Endpoints (/play/dev)

These are server-to-server endpoints for game backends. They require HMAC authentication and only the game owner/creator can access them.

• POST /play/dev/batch-save-points - Batch save player points (rate limit: 3/sec)

• GET /play/dev/points - Get player points for today

• GET /play/dev/leaderboard/:gameId - Get game leaderboard

• GET /play/dev/sessions/:gameId - Get player sessions with anti-cheat data

• GET /play/dev/risky-sessions/:gameId - Get flagged sessions (risk score > 0.5)

• POST /play/dev/invalidate-sessions - Invalidate fraudulent sessions and remove points

Play — Client Endpoints (/play)

These are used by the Vanilla JS SDK (client-side). They use session token auth and the flush/commit protocol for anti-cheat.

• POST /play/flush - Flush points incrementally with hash chain proof (rate limit: 1/sec)

• POST /play/commit - Commit session points (rate limit: 1/5sec)

• GET /play/session-state - Get current session state for resync

• GET /play/session-token - Get a player session token

• GET /play/get-points - Get player's current points

User (/user)

• GET /user/me - Get current user

• POST /user/hmac-signature - Generate HMAC signature (unauthenticated helper)

• GET /user/me/stats - Get user statistics

• POST /user/reset-secret - Reset API secret key

Token Launcher (/token-launcher)

• POST /token-launcher/launch - Launch a Playcoin

• GET /token-launcher/launch/:jobId - Check launch status

Multiplier (/multiplier)

• GET /multiplier/cost - Calculate multiplier purchase cost

• GET /multiplier/current - Get player's current multiplier

• GET /multiplier/cost-for-placement - Calculate cost for leaderboard position

• POST /multiplier/purchase - Purchase a multiplier

Rewards (/rewards)

• GET /rewards/game-rewards-pool/:gameId - Get game rewards pool info

Player Identifier Formats (Dev Endpoints)

Dev endpoints accept flexible player identifiers in type:value format:

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

Users are auto-created via Privy if they don't exist. The response includes a playerIdToOgpId mapping — cache this for better performance on subsequent requests.

Rate Limits

Endpoint	Limit
Default	60 requests per minute
POST /play/flush	1 request per second
POST /play/commit	1 request per 5 seconds
POST /play/dev/batch-save-points	3 requests per second

Error Responses

All errors follow a standard format:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Common status codes:

• 400 - Bad Request (validation error, invalid identifier format)

• 401 - Unauthorized (invalid/missing auth, invalid HMAC signature)

• 403 - Forbidden (not game owner/creator)

• 404 - Not Found

• 429 - Too Many Requests (rate limited)

• 500 - Internal Server Error

SDKs

For easier integration, use our official SDKs:

• Vanilla JS SDK - Browser-based games

• Server SDK - Backend integrations

• React Examples - React integration patterns