# Rewards

List published reward campaign awards for the root account and record their payout destinations.

`client.rewards` reads the reward campaign awards published to the authenticated root account and records where an award is paid. Every method needs a session JWT; API keys are not accepted. Tree-shaken builds reach the same service with `rewardsService(core)` from `@polyester/sdk/services/rewards`.

Daily claims are a separate service: see [`client.claims`](https://testnet.polyester.com/docs/sdk/typescript/reference/account-services#clientclaims).

## Methods

| Method           | Summary                                                 |
| ---------------- | ------------------------------------------------------- |
| `listAwards`     | List published awards, newest first.                    |
| `setDestination` | Record the write-once payout destination for one award. |

### `listAwards(input?, options?)`

Returns `{ awards, nextPageToken }`, ordered by publication time and award ID, newest first. `limit` is 0 through 100; 0 or omitted uses 50. Pass the previous `nextPageToken` as `pageToken` to continue. An empty `nextPageToken` means no more awards. `pageToken` is at most 256 characters.

```ts
let pageToken = "";
do {
	const page = await client.rewards.listAwards({ limit: 100, pageToken });
	for (const award of page.awards) {
		console.log(award.campaignName, award.amountBaseUnits, award.fulfillmentState);
	}
	pageToken = page.nextPageToken;
} while (pageToken !== "");
```

#### `RewardAward`

```ts
interface RewardAward {
	awardId: string;
	campaignId: string;
	campaignName: string; // frozen at publication
	assetId: number;
	amountBaseUnits: string; // exact integer in the asset's smallest unit
	fulfillmentMethod: "external_testnet" | "internal_trading" | "unspecified";
	fulfillmentState:
		| "awaiting_destination"
		| "ready_for_payout"
		| "paid"
		| "failed"
		| "canceled"
		| "unspecified";
	publishedAt?: number; // epoch ms
	network: string; // payout network; destinationAddress is read in it
	fulfillmentRevision: string; // pass as expectedRevision
	destinationAddress: string; // "" until provided
	transactionId: string; // "" until delivery is recorded
}
```

`amountBaseUnits` is an exact integer string in the asset's smallest base unit, not a decimal amount. Keep it as a string or `bigint`; do not parse it to `number`.

### `setDestination(input, options?)`

Records the payout destination for an award owned by the authenticated root account, returning `{ award }` with the stored destination and updated `fulfillmentState`. The destination is write-once and is interpreted in the award's `network`. It does not execute a transfer or mark the award delivered.

The call needs a fresh step-up proof as `stepUpToken`. See [MFA](https://testnet.polyester.com/docs/sdk/typescript/reference/mfa) and [Error handling](https://testnet.polyester.com/docs/sdk/typescript/guides/error-handling) for the step-up retry pattern.

```ts
const { award: updated } = await client.rewards.setDestination(
	{
		awardId: award.awardId,
		destinationAddress,
		expectedRevision: award.fulfillmentRevision,
		requestId: crypto.randomUUID(),
	},
	{ stepUpToken }
);
console.log(updated.fulfillmentState, updated.destinationAddress);
```

| Field                | Type     | Notes                                                          |
| -------------------- | -------- | -------------------------------------------------------------- |
| `awardId`            | `string` | 1 to 128 characters.                                           |
| `destinationAddress` | `string` | 1 to 512 characters, in the award's `network`.                 |
| `expectedRevision`   | `string` | The award's `fulfillmentRevision`, a positive decimal string.  |
| `requestId`          | `string` | Client-generated, 1 to 128 characters. Reuse it when retrying. |

## Related

- [Account services](https://testnet.polyester.com/docs/sdk/typescript/reference/account-services) for daily claims and the other account-level services.
- [MFA](https://testnet.polyester.com/docs/sdk/typescript/reference/mfa) for step-up proofs.
- [Errors](https://testnet.polyester.com/docs/sdk/typescript/reference/errors) for the error type reference.