Skip to main content
Query the rewards available in a point system, with optional per-wallet breakdown of eligibility and claim status.

​
GET /api/sdk/rewards

​
Request

GET https://api.rewards.so/rewards?pointSystemId=your-uuid[&address=0xabc123...]
Authorization: Bearer rw_your_api_key

​
Query parameters

ParameterTypeRequiredDescription
pointSystemIdstringYesUUID of the point system
addressstringNoIf provided, returns per-wallet breakdown

​
Without address — all rewards

Returns every reward for the point system regardless of wallet.

​
Response 200

{
  "rewards": [
    {
      "id": "1ebeaa49-736a-43c8-97fb-69a406fbf892",
      "campaignId": "CMP-2WB39F",
      "campaignName": "Season 1 Airdrop",
      "tokenType": "ethereum",
      "tokenAddress": null,
      "chainId": 50312,
      "totalAmount": 0.5,
      "minPoints": 100,
      "maxPoints": 2600,
      "allocationType": "proportional",
      "status": "active",
      "claimDeadline": "2026-04-11T10:00:00.000Z",
      "createdAt": "2026-04-09T00:54:34.051Z"
    }
  ]
}

​
Reward fields

FieldTypeDescription
idstringReward UUID
campaignIdstringShort human-readable campaign ID (e.g. CMP-2WB39F)
campaignNamestringDisplay name
tokenTypestringethereum, erc20, etc.
tokenAddressstring | nullERC-20 contract address, null for native tokens
chainIdnumber | nullEVM chain ID
totalAmountnumberTotal token amount allocated to this reward
minPointsnumberMinimum points required to be eligible
maxPointsnumber | nullPoints cap used in proportional distribution
allocationTypestringproportional — allocation scales with points
statusstringpending, active, distributed, cancelled
claimDeadlinestring | nullISO 8601 deadline, or null if open-ended
createdAtstringISO 8601 creation date

​
With address — per-wallet breakdown

Returns the same rewards split into three buckets based on the wallet’s eligibility and claim history.

​
Response 200

{
  "address": "0x3d73d19f3daf0cd6ea798c49939336b00adff988",
  "totalPoints": 2610,
  "rewards": {
    "eligible": [
      {
        "id": "...",
        "campaignName": "Season 1 Airdrop",
        "totalAmount": 0.5,
        "allocatedAmount": 0.35,
        "status": "active",
        "claimDeadline": "2026-04-11T10:00:00.000Z"
      }
    ],
    "claimed": [
      {
        "id": "...",
        "campaignName": "Early Access Drop",
        "claimedAmount": 1.2,
        "claimedAt": "2026-04-08T14:00:00.000Z",
        "claimTxHash": "0xabc..."
      }
    ],
    "unavailable": [
      {
        "id": "...",
        "campaignName": "VIP Reward",
        "minPoints": 5000,
        "pointsNeeded": 2390
      }
    ]
  }
}

​
Buckets

BucketCondition
eligibleWallet has a distribution allocated but hasn’t claimed yet
claimedWallet has already claimed this reward
unavailableWallet doesn’t meet the minimum points requirement

​
Extra fields in per-wallet mode

FieldBucketDescription
allocatedAmounteligibleToken amount allocated to this wallet (null if not yet distributed)
claimedAmountclaimedToken amount that was claimed
claimedAtclaimedISO 8601 claim timestamp
claimTxHashclaimedOn-chain transaction hash
pointsNeededunavailableHow many more points needed to reach minPoints

​
Code examples

type RewardsForWallet = {
  address: string;
  totalPoints: number;
  rewards: {
    eligible: object[];
    claimed: object[];
    unavailable: object[];
  };
};

async function getWalletRewards(
  pointSystemId: string,
  address: string
): Promise<RewardsForWallet> {
  const url = new URL("https://api.rewards.so/rewards");
  url.searchParams.set("pointSystemId", pointSystemId);
  url.searchParams.set("address", address);

  const res = await fetch(url.toString(), {
    headers: { Authorization: `Bearer ${process.env.REWARDS_API_KEY}` },
  });

  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Usage
const data = await getWalletRewards(POINT_SYSTEM_ID, userAddress);
console.log(`${data.rewards.eligible.length} rewards available to claim`);
console.log(`${data.rewards.claimed.length} already claimed`);