Rewards

Rewards endpoints allow players to claim rewards after completing offers or referral requirements.

Endpoints Overview

Endpoint	Auth	Description
`POST /client/reward/claim`	JWT	Claim rewards from client
`POST /reward/sdk/claim`	API Key	Claim rewards from server

Claim Reward (Client)

Claim rewards for a completed offer or referral from the client-side.

Endpoint

POST /client/reward/claim

Authentication

JWT - Requires x-game-jwt header. The playerId and gameId are extracted from the JWT.

Request

{
  kind: 'offer' | 'referral';  // Type of reward to claim
  instanceId: string;          // ID of the offer instance or referral instance
}

curl -X POST https://api.pixels.xyz/v1/client/reward/claim \
  -H "Content-Type: application/json" \
  -H "x-game-jwt: YOUR_JWT_TOKEN" \
  -d '{
    "kind": "offer",
    "instanceId": "instance-def456"
  }'

Response

{
  message: string;  // Success message
}

{
  "message": "success"
}

Example Usage

async function claimOfferReward(jwt: string, offer: IClientOffer) {
  // Check if offer is claimable
  if (offer.status !== 'claimable') {
    console.error('Offer is not claimable yet');
    return;
  }

  const response = await fetch('https://api.pixels.xyz/v1/client/reward/claim', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-game-jwt': jwt
    },
    body: JSON.stringify({
      kind: 'offer',
      instanceId: offer.instanceId
    })
  });

  const { message } = await response.json();
  console.log('Claimed:', message);
}

Claim Reward (Server)

Claim rewards for a player from your server-side code.

Endpoint

POST /reward/sdk/claim

Authentication

API Key - Requires x-api-key and x-client-id headers

Request

{
  kind: 'offer' | 'referral';  // Type of reward to claim
  instanceId: string;          // ID of the offer instance or referral instance
  playerId: string;            // Required - Player's unique ID
}

curl -X POST https://api.pixels.xyz/v1/reward/sdk/claim \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -d '{
    "kind": "offer",
    "instanceId": "instance-def456",
    "playerId": "player-123"
  }'

Response

{
  message: string;    // Success message
  rewards: IReward[]; // Rewards that were distributed
}

{
  "message": "success",
  "rewards": [
    {
      "kind": "item",
      "rewardId": "gems",
      "name": "Gems",
      "amount": 50,
      "image": "https://cdn.example.com/gems.png"
    },
    {
      "kind": "coins",
      "rewardId": "gold",
      "name": "Gold Coins",
      "amount": 100,
      "image": "https://cdn.example.com/gold.png"
    }
  ]
}

Example Usage

async function claimRewardServerSide(playerId: string, instanceId: string) {
  const response = await fetch('https://api.pixels.xyz/v1/reward/sdk/claim', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.STACKED_API_KEY!,
      'x-client-id': process.env.STACKED_CLIENT_ID!
    },
    body: JSON.stringify({
      kind: 'offer',
      instanceId,
      playerId
    })
  });

  const { message, rewards } = await response.json();

  console.log(`Player ${playerId} claimed ${rewards.length} rewards`);

  return { message, rewards };
}

Reward Types

Kind	Description
`item`	In-game items (gems, potions, equipment)
`coins`	In-game currency (gold, credits)
`exp`	Experience points
`trust_points`	Reputation/trust score
`loyalty_currency`	Premium/loyalty currency

Claiming Rewards

Always check offer.status === 'claimable' before claiming. Attempting to claim rewards for offers with other statuses will fail.

Rewards

On this page