Play & Rewards

API Reference: https://api.play.fun/api-reference

Authentication

For developer endpoints, you need HMAC authentication. See API Reference - Authentication for details on generating signatures.

All dev endpoints also require the header:

x-auth-provider: hmac

---

Play Endpoints

Batch Save Points

POST /play/dev/batch-save-points

Save points for multiple players in a single request. This is the recommended way to update player scores from your game backend.

Headers:

Content-Type: application/json
x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Request Body:

{
  "gameApiKey": "your-game-owner-id",
  "points": [
    {
      "playerId": "sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC",
      "points": "1500"
    },
    {
      "playerId": "email:[email protected]",
      "points": "2300"
    },
    {
      "playerId": "550e8400-e29b-41d4-a716-446655440000",
      "points": "500"
    }
  ]
}

Player ID Formats:

Format	Example	Description
Solana Wallet	sol:9qdvVLY... or solana:9qdvVLY...	Resolves by Solana address, auto-creates user
Ethereum Wallet	eth:0x123... or ethereum:0x123...	Resolves by ETH address, auto-creates user
Email	email:[email protected]	Resolves by email, auto-creates user
Twitter/X	twitter:username or x:username	Resolves by Twitter/X handle, auto-creates user
Privy ID	did:privy:abc123...	Direct Privy user lookup
OGP User ID	550e8400-e29b-41d4-...	Raw UUID, fastest (no resolution needed)

Identifiers that are not in type:value format and are not valid UUIDs will throw an error. The identifier parser only accepts the formats listed above.

Response:

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

JavaScript Example:

async function savePlayerScores(scores) {
  const signature = await getSignature('POST', '/play/dev/batch-save-points');

  const response = await fetch('https://api.play.fun/play/dev/batch-save-points', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-auth-provider': 'hmac',
      Authorization: signature,
    },
    body: JSON.stringify({
      gameApiKey: 'your-game-owner-id',
      points: scores.map((score) => ({
        playerId: score.walletAddress ? `sol:${score.walletAddress}` : score.ogpId,
        points: score.points.toString(),
      })),
    }),
  });

  if (!response.ok) {
    throw new Error(`Failed to save points: ${response.status}`);
  }

  return await response.json();
}

// Usage
await savePlayerScores([
  { walletAddress: '9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC', points: 1500 },
  { ogpId: '550e8400-e29b-41d4-a716-446655440000', points: 2300 },
]);

Notes:

• Points are cumulative — they add to existing points for the day

• Users are automatically created if they don't exist (via Privy)

• Cache the playerIdToOgpId mapping for better performance on subsequent requests

• Only the game owner/creator can save points

• Maximum 1000 entries per batch request

• Rate limit: 3 requests per second

---

Get Player Points

GET /play/dev/points

Retrieve the current day's points for a specific player in your game.

Headers:

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

Query Parameters:

• gameId (required) - Your game's UUID

• playerId (required) - Player identifier (same formats as batch-save-points)

Example Request:

curl "https://api.play.fun/play/dev/points?gameId=c8d75cec-d66f-46df-b0eb-e2065e7ccea3&playerId=sol:9qdvVLY3vLhmvV7uBkLJsQKcHDjxhoUWJ9uZASYEfwwC" \
  -H "x-auth-provider: hmac" \
  -H "Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=..."

Response:

{
  "points": "1500",
  "ogpId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

Get Game Leaderboard

GET /play/dev/leaderboard/{gameId}

Retrieve the leaderboard for your game. Returns top players ranked by points.

Headers:

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

Path Parameters:

• gameId (required) - Your game's UUID

Query Parameters:

• limit (optional, default: 10, max: 100) - Number of entries to return

• cursor (optional) - Pagination cursor for next page

• date (optional, default: today) - Date in YYYY-MM-DD format

Response:

{
  "items": [
    {
      "ogpId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "points": "15000",
      "estimatedUsdValue": 25.5
    }
  ],
  "nextCursor": "cursor-string",
  "hasMore": false,
  "total": 245,
  "estimatedDailyRewardsUsd": 1000.0
}

Notes:

• Leaderboards are calculated per day

• Only shows PLAYER type points (not referrer/distributor points)

• Rejected/invalidated points are excluded

• Only the game owner/creator can access leaderboards

---

Get Player Sessions

GET /play/dev/sessions/{gameId}

Retrieve player sessions for your game, including anti-cheat and fraud detection data.

Headers:

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

Path Parameters:

• gameId (required) - Your game's UUID

Query Parameters:

• date (optional, YYYY-MM-DD) - Filter by date

• userId (optional, UUID) - Filter by player user ID

• minRiskScore (optional, 0-1) - Minimum risk score filter

• status (optional) - valid, pending_review, or invalidated

• limit (optional, default: 50, max: 100) - Results per page

• cursor (optional) - Pagination cursor

Response:

{
  "items": [
    {
      "id": "session-uuid",
      "userId": "user-uuid",
      "gameId": "game-uuid",
      "date": "2025-11-28",
      "points": "1000",
      "sessionStartMs": "1705300000000",
      "sessionEndMs": "1705301800000",
      "durationMs": 1800000,
      "flushCount": 5,
      "finalSeq": 18,
      "clientInstanceId": "client-uuid",
      "clientInstanceIdChanges": 0,
      "riskScore": 0.25,
      "riskReasons": ["unusual_flush_pattern"],
      "status": "valid",
      "referrerId": null,
      "distributorIds": null,
      "referrerPoints": 0,
      "createdAt": "2025-11-28T10:00:00Z"
    }
  ],
  "nextCursor": "cursor-string",
  "hasMore": false,
  "total": 52
}

Session Fields:

• riskScore (0-1): Fraud detection score. Higher = more suspicious

• riskReasons: Array of detected anomalies (e.g., unusual_flush_pattern, multiple_client_instances)

• status: valid (accepted), pending_review (under review), invalidated (removed)

• flushCount: Number of flush operations in session

• clientInstanceIdChanges: Count of device/client changes (indicator of device switching)

---

Get Risky Sessions

GET /play/dev/risky-sessions/{gameId}

Same as Get Sessions, but filtered to sessions with riskScore > 0.5. Use this to review suspicious activity.

Query Parameters:

• date (optional, YYYY-MM-DD)

• limit (optional, default: 50, max: 100)

• cursor (optional)

---

Invalidate Sessions

POST /play/dev/invalidate-sessions

Invalidate fraudulent sessions and remove their associated points. This fully reverts the session's impact, including referrer and distributor points.

Headers:

Content-Type: application/json
x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Request Body:

{
  "gameId": "game-uuid",
  "sessionIds": ["session-uuid-1", "session-uuid-2"],
  "reason": "Suspected fraud - unusual activity pattern"
}

Response:

{
  "invalidatedCount": 2,
  "pointsRemoved": 2500
}

Notes:

• Maximum 100 sessions per request

• Cascading removal: also removes referrer and distributor points linked to the session

• Fully auditable: reason, admin ID, and timestamp are recorded

• Only the game owner/creator can invalidate sessions

---

Validate Session Token

POST /play/dev/validate-session-token

Validate a player session token (player_xxx) issued by the client SDK. Use this to verify that a player sending requests to your backend is genuinely authenticated through Play.fun.

Headers:

Content-Type: application/json
x-auth-provider: hmac
Authorization: HMAC-SHA256 apiKey=... signature=... timestamp=...

Request Body:

{
  "sessionToken": "player_abc123..."
}

Response (valid token):

{
  "valid": true,
  "playerId": "did:privy:abc123",
  "gameId": "c8d75cec-d66f-46df-b0eb-e2065e7ccea3",
  "ogpId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response (invalid token):

{
  "valid": false
}

Response Fields:

Field	Type	Description
valid	boolean	Whether the token is valid
playerId	string	Privy ID (did:privy:xxx) — use to verify the player matches who you expect
gameId	string	Game UUID the token was issued for
ogpId	string	Internal OGP user UUID — use as playerId in savePoints / batchSavePoints for best performance

Notes:

• Session tokens are scoped per-game and expire after 30 minutes

• The ogpId in the response can be passed directly to savePoints / batchSavePoints to skip identifier resolution

• Only the game owner/creator can validate tokens for their game

---

Rewards Endpoints

Get Game Rewards Pool

GET /rewards/game-rewards-pool/{gameId}

Get the total rewards pool value and breakdown by token for a specific game.

Path Parameters:

• gameId (required) - Game UUID

Example Request:

curl "https://api.play.fun/rewards/game-rewards-pool/c8d75cec-d66f-46df-b0eb-e2065e7ccea3"

Response:

{
  "tokens": {
    "So11111111111111111111111111111111111111112": {
      "allocatedRewardsUsd": 8500.0,
      "totalAvailableAtomic": "50500000000",
      "image": "https://...",
      "name": "Solana",
      "symbol": "SOL"
    }
  },
  "totalRewardsPoolUsdValue": 15420.5
}

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request:

{
  "statusCode": 400,
  "message": "Invalid identifier format: \"bad-id\"",
  "error": "Bad Request"
}

401 Unauthorized:

{
  "statusCode": 401,
  "message": "Invalid HMAC signature",
  "error": "Unauthorized"
}

403 Forbidden:

{
  "statusCode": 403,
  "message": "Only the game owner or creator can perform this action",
  "error": "Forbidden"
}

429 Too Many Requests:

{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "error": "Too Many Requests"
}

500 Internal Server Error:

{
  "statusCode": 500,
  "message": "Error adding points",
  "error": "Internal Server Error"
}