# Reward methods

> Client methods for balances, lotteries, entries and claims.

Source: https://dashboard.adquest.batriders.ir/docs/sdk/rewards · Audience: Developers · Section: SDK reference

## getTokenBalance

### `getTokenBalance`

Reads the participant’s token balance. Needs a participant token.

```typescript
getTokenBalance(): Promise<TokenBalance>
```

**Returns:** A Promise of { tokens, platformUserId, externalUserId, available?, pending?, lifetime? }.

## getTokenBalanceHistory

### `getTokenBalanceHistory`

Reads the participant’s token transactions, newest first. Needs a participant token.

```typescript
getTokenBalanceHistory(options?: { page?: number; perPage?: number }): Promise<TokenLedgerHistoryResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| options.page | number | no | Page number. |
| options.perPage | number | no | Items per page. |

**Returns:** A Promise of { items, currentPage, lastPage, total, perPage }.

## getLotteries

### `getLotteries`

Lists lotteries visible to the participant. Needs a participant token.

```typescript
getLotteries(options?: GetLotteriesOptions): Promise<LotteryListResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| options.filter | LotteryFilter | no | active (default), upcoming, completed or all. |
| options.page | number | no | Page number. |
| options.perPage | number | no | Items per page. |

**Returns:** A Promise of { lotteries, pagination }.

## getLottery

### `getLottery`

Loads one lottery with its prizes and the participant’s own entry count. Needs a participant token.

```typescript
getLottery(lotteryId: number): Promise<LotteryDetail>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| lotteryId | number | yes | Lottery ID. |

**Returns:** A Promise of LotteryDetail.

## enterLottery

### `enterLottery`

Spends tokens to buy entries. Create one idempotency key for each purchase attempt and reuse it when you retry after an uncertain response. Needs a participant token.

```typescript
enterLottery(lotteryId: number, options: EnterLotteryOptions): Promise<LotteryPurchase>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| lotteryId | number | yes | Lottery ID. |
| options.entryCount | number | yes | Entries to buy, 1 to 100. |
| options.idempotencyKey | string | yes | Unique key for this purchase attempt. |

**Returns:** A Promise of LotteryPurchase: { id, lotteryId, entryCount, unitCostTokens, totalCostTokens, status, ticketNumbers, eligibilitySnapshot? }.

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

const purchase = await client.enterLottery(4, {
  entryCount: 2,
  idempotencyKey: createIdempotencyKey(),
});
```

## getMyLotteryEntries

### `getMyLotteryEntries`

Lists the participant’s entries and purchases for one lottery. Needs a participant token.

```typescript
getMyLotteryEntries(lotteryId: number): Promise<MyLotteryEntriesResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| lotteryId | number | yes | Lottery ID. |

**Returns:** A Promise of { entries, purchases, entryCount }.

## getLotteryResults

### `getLotteryResults`

Returns the winners once the lottery is completed. Before that, winners is empty. Needs a participant token.

```typescript
getLotteryResults(lotteryId: number): Promise<LotteryResults>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| lotteryId | number | yes | Lottery ID. |

**Returns:** A Promise of { lifecycleStatus, winners }.

## getMyClaims

### `getMyClaims`

Lists the prizes the participant has won. Needs a participant token.

```typescript
getMyClaims(): Promise<LotteryClaim[]>
```

**Returns:** A Promise of LotteryClaim[].

## submitLotteryClaim

### `submitLotteryClaim`

Submits the winner’s claim details. A submitted claim is not a promise that fulfillment is complete. Needs a participant token.

```typescript
submitLotteryClaim(claimId: number, payload: SubmitClaimPayload): Promise<LotteryClaim>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| claimId | number | yes | Claim ID from getMyClaims. |
| payload | Record<string, unknown> | yes | The claim details the prize requires. |

**Returns:** A Promise of the updated LotteryClaim.

## Next steps

- [Tokens, lotteries & claims](https://dashboard.adquest.batriders.ir/docs/rewards): How to enter a lottery safely.
- [AdQuestError](https://dashboard.adquest.batriders.ir/docs/sdk/errors): Handle errors from these methods.