Rewards

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.

Methods

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.

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

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 and Error handling for the step-up retry pattern.

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

Related

• Account services for daily claims and the other account-level services.
• MFA for step-up proofs.
• Errors for the error type reference.

Related Topics