# Tokens, lotteries & claims

> Read participant balances, enter lotteries and manage claims using authenticated server results.

Source: https://dashboard.adquest.batriders.ir/docs/rewards · Audience: Developers · Section: Build

## Prerequisites

- A participant token for the signed-in user.
- A client from the headless guide, or the React widget.

## Read participant rewards

Use getTokenBalance() and getTokenBalanceHistory() with a participant token. Quest tokenReward and completion tokensAwarded describe the participant’s reward share. Advertiser credits fund distribution and are separate from participant tokens. Refresh balance after confirmed quest completion or a lottery purchase.

> **Completion is authoritative on the server.** Display the actual settlement result. Do not increment a permanent balance using only a client callback, animation, click or an intermediate success response.

## Enter a lottery safely

1. Read active lotteries and show the selected lottery’s cost, rules, entry limits and deadline.
2. Let the participant choose an entry count and explicitly confirm the purchase.
3. Create one idempotency key for that purchase attempt, submit it, and reuse the same key when retrying an uncertain response.
4. Refresh the participant’s balance and entries after confirmation.

**After the participant confirms the selected lottery**

```typescript
import { createIdempotencyKey } from "@adquest/sdk";

const idempotencyKey = createIdempotencyKey();
const purchase = await client.enterLottery(selectedLotteryId, {
  entryCount: selectedEntryCount,
  idempotencyKey,
});
// Retain idempotencyKey if this same purchase needs a retry.
const balance = await client.getTokenBalance();
const entries = await client.getMyLotteryEntries(selectedLotteryId);
```

## Results and claims

Read getLotteryResults(id) for results and getMyClaims() for available claims. Use submitLotteryClaim(id, payload) with the required claim details. The ready-made widget handles the claim form; headless hosts must render the required fields and honor claim availability and deadlines. A submitted claim is not a promise that fulfillment is complete.

- Test insufficient tokens, closed lotteries, entry limits and duplicate purchase responses.
- Test no-win results, available claims, expired claims and a retried submission.

## Reward country and availability

A lottery can be limited to some countries. The decision uses one input: the eligibility country your backend sent as country_code when it created the session. It is never taken from language, GeoIP or the browser.

| Lottery policy | Country known and allowed | Country known and not allowed | Country unknown |
| --- | --- | --- | --- |
| global | Visible, entry allowed | Visible, entry allowed | Visible, entry allowed |
| fulfillment | Visible, entry allowed | Hidden, entry refused (404 LOTTERY_NOT_AVAILABLE) | Visible with availability.warning true, entry allowed |
| legal | Visible, entry allowed | Hidden, entry refused (404 LOTTERY_NOT_AVAILABLE) | Hidden, entry refused |

- Omit country_code when you do not know it. An empty value clears the stored country. An invalid code returns 422 VALIDATION_ERROR.
- platform_user.country_code in the session response is analytics data. Reward rules use eligibility_country_code and eligibility_country_source.
- Each entry stores a snapshot of the country, its source, the eligibility result and the policy version, and returns it as eligibility_snapshot.

## Next steps

- [Webhooks](https://dashboard.adquest.batriders.ir/docs/webhooks): Get notified of completions and winners.
- [Test & go live](https://dashboard.adquest.batriders.ir/docs/launch): Check lotteries, claims and retries.