Rewards Track rewards

Track rewards

Poll durable reward resources and display status without inventing settlement.

Use the read API to follow an accepted reward. Outgoing webhooks are not part of the initial integration, so your backend should poll and cache the status it needs for your application.

Read a known reward#

const reward = await slices.rewards.get("rwd_demo0001");

const display = {
  id: reward.id,
  amountBaseUnits: reward.amountBaseUnits,
  status: reward.status,
  recipient: reward.recipient.verificationStatus,
  verificationUrl: reward.recipient.verificationUrl,
  reason: reward.statusReason,
  transaction: reward.deliveryEvidence?.transactionHash ?? null,
  checkedAt: reward.deliveryEvidence?.checkedAt ?? null,
};

Run this on your server. Expose only the current authenticated user's authorized reward records through your own frontend API. Do not give a browser the Slices server key or let a user read arbitrary reward IDs without your own authorization check.

Poll on a schedule, not inside issuance#

Record the reward ID when issuance succeeds. Use a scheduled job to refresh outstanding records and store the latest result locally. For a small pilot, a refresh roughly once per minute is a reasonable starting application policy—not a Slices delivery SLA or mandatory polling interval.

Stagger work, bound concurrency, and account for the project-wide request limit. Polling 100 rewards individually once per minute can consume most of the default quota before issuance and other reads are counted. Use paginated filtered lists when suitable, and poll rewards that are waiting on your operator less often.

If a request returns 429, respect Retry-After and reduce traffic. Never poll in a tight loop or keep a serverless request open waiting for the operator to send.

A UI model that preserves the distinctions#

Condition	Useful language
`accepted` with `recipient.verificationStatus: unverified`	“Reward recorded. Verify your wallet to receive it.”, linking `recipient.verificationUrl`
`accepted` with a verified recipient	“Reward recorded.”
`queued`	“Awaiting approval.”
`approved`	“Approved. Waiting for the operator to send the transfer.”
`sent`	“Transfer sent. Waiting for confirmation.”
`delivered`	“Transfer confirmed.”
`failed`	“The transfer did not complete. The operator can retry it.”
`cancelled`	“This reward was cancelled before it was sent.”
A read that failed	“Showing the last known status. Refresh is delayed.”

Do not display “paid” immediately after acceptance. Keep the original reward amount separate from a current wallet balance or estimated market value.

Freshness and errors#

Use deliveryEvidence.checkedAt for the freshness of chain evidence and updatedAt for changes to the Slices resource. If a read fails, preserve your last known record with an error or stale indicator. Do not replace the reward amount with zero or assume the grant no longer exists.

A database-backed read returns the last verified status even while the chain's RPC is unavailable; a sent reward stays sent until the job can verify its receipt. When Slices cannot serve a trustworthy response at all, handle the error rather than inventing a successful empty result.

When to stop frequent polling#

Cancelled rewards need no further polling. Delivered rewards normally leave the active work queue, but retain their IDs and audit history: evidence can be corrected after an incident. Perform lower-frequency reconciliation for your own reporting where needed.

A queued or approved reward is not a failed reward: it is waiting on your operator and needs a slower poll, not a new reward. A failed reward stays with the same ID until the operator retries it or closes the draft campaign.

Related: Get a reward, List rewards, and Webhooks.