Rewards and claims
What a quest pays, how a fan claims it, and the loot box reveal.
What a fan gets for a quest, and the part of the build fans remember.
Reward types
Every reward carries a slug identifying its type. Eight are live:
| Slug | What the fan gets | After the claim |
|---|---|---|
give_resources | XP or currency. The most common reward by volume. | Credited. Show the amount. |
give_resources_progressive | The same, at a fixed amount that does not shrink | Credited |
give_assets | An inventory item | In their inventory |
give_prizes | A prize. May need an email or an address first. | Granted, then shipped if physical |
give_lootboxes | A loot box | The reveal |
give_personalizations | A cosmetic: a profile picture, border or background | Ready to equip |
assign_discord_role | A role in your Discord | Assigned on Discord |
manual_claim_reward | Something your team hands over by hand | Nothing automatic. Show the name. |
An unknown slug renders nothing. That keeps a reward type added after you ship from appearing as a broken card.
A give_resources reward carries whether the resource is spendable:
{
"slug": "give_resources",
"rewardHandlerArgs": {
"amount": 20,
"resourceTypeId": "urn:xb-resource:…",
"slug": "xp",
"name": "XP",
"isSpendable": false
}
}isSpendable is the one to read. A non-spendable resource is progression, XP and
levels, and a spendable one is currency the fan can use in the store.
Showing both with the same treatment is a common early mistake.
A quest can carry several rewards at once, commonly a prize alongside the resources for completing it, so render them as a list rather than reaching for the first one.
Showing rewards before completion
Fans decide whether a quest is worth doing by looking at the reward, so render it up front. The rewards are on the quest itself, and they render signed out.
import { resolveQuestRewardChrome, useQuest } from '@xborglabs/fanbase-react'
function QuestRewards() {
const { state } = useQuest()
const quest = state.quest
return (
<ul className="your-rewards">
{quest?.rewards?.map((reward) => {
const chrome = resolveQuestRewardChrome({ reward, quest })
if (!chrome) return null
return (
<li key={reward.rewardConfigurationId}>
{chrome.imageSrc && <img src={chrome.imageSrc} alt="" />}
<span>{chrome.label ?? chrome.name}</span>
</li>
)
})}
</ul>
)
}Do not branch on slug strings you have hardcoded. resolveQuestRewardChrome returns the image, name, amount and a ready-made label like 20 XP for any live slug, and undefined for one it does not know. New reward types then work without a code change.
The amount it gives is the right one for the moment. Before completion that is the configured amount, including any reduction your community team set for later finishers. After completion it is the amount the fan was actually paid, which is locked.
Claim state
Whether a reward is waiting to be claimed lives on its allocation, and allocations need a session. Ask the provider to fetch them:
<Quest.Provider questId={questId} fetchRewards>fetchRewards is a flag, and it is off by default. Leave it off on a list, and turn it on for the detail page where the claim button is. With it on, state.rewards holds the allocations and state.canClaim knows whether one is waiting.
Signed out, there is nothing to fetch and the provider does not try.
Claiming
When state.canClaim is true there is something waiting.
<Quest.Claim asChild>
<button className="your-button">{state.buttonLabel}</button>
</Quest.Claim>buttonLabel already says the right thing for the claim state, so you do not need your own copy.
A quest with more than one reward has more than one allocation. Quest.Claim claims them all. If you are wiring your own control, use actions.claimAllAllocated() rather than actions.claim, which claims the single allocation you name and leaves the rest waiting.
Claims that need details
Some prizes need something from the fan before they can be sent. An email for a code, an address for merchandise, a wallet for an on-chain item.
Until the fan provides it, the machine holds the claim with REWARD_REQUIREMENT_REQUIRED. Collect the details, build the payload with the builder the SDK ships for this call, and hand it to the provider:
import { toAllocationClaimPayload } from '@xborglabs/fanbase-react'
const claimPayload = toAllocationClaimPayload(values)
<Quest.Provider questId={questId} fetchRewards claimPayload={claimPayload}>The requirements are on the reward, in rewardHandlerArgs.requirements. Prizes and inventory shows how to turn them into form fields, which is the same for a quest, a loot box and a store purchase.
Do not build the payload by hand. The same three fields are sent in three different shapes to three different endpoints, and toAllocationClaimPayload is the one for a quest claim.
Collect the details before the fan presses claim. A claim that fails validation is a worse moment than one extra field.
Delivery
After a claim, an allocation has two statuses, and together they say where the reward is:
claimStatus | distributionStatus | Means | Show |
|---|---|---|---|
ALLOCATED | ALLOCATED | Waiting to be claimed | The claim button |
CLAIMED | ALLOCATED | Claimed, still being delivered | Processing |
CLAIMED | DISTRIBUTED | The fan has it | Done |
Physical prizes can sit at claimed and processing for a while. That is fulfilment, not a failure.
Loot boxes
The one flow with a wait in it, and worth building properly because it is the most fun moment in the product.
The reward slug is give_lootboxes. Claiming it opens the box. The contents resolve on the server a moment later, and your overlay covers that gap.
import {
buildLootboxListingFallback,
getQuestRewardAllocations,
resolveLootboxSelectedItem,
useFanbase,
useLootboxes,
useQuest,
} from '@xborglabs/fanbase-react'
function LootboxReveal({ lootboxId }) {
const { meta } = useFanbase()
const { state, actions } = useQuest()
const [opening, setOpening] = useState(null)
const [waiting, setWaiting] = useState(false)
const { data: boxes } = useLootboxes({ lootboxIds: [lootboxId] }, Boolean(opening))
async function open() {
setWaiting(true)
await actions.claimAllAllocated()
// the contents are not in the claim response: poll until they land
const found = await pollUntil(
async () => {
const { allocations } = await getQuestRewardAllocations(meta.http, state.questId)
return allocations.find((a) => a.lootboxOpening?.selectedItem)?.lootboxOpening
},
{ intervalMs: 700, timeoutMs: 20000 },
)
setOpening(found ?? null)
setWaiting(false)
}
const possibleItems = boxes?.[0]?.items?.length
? boxes[0].items
: opening?.selectedItem
? buildLootboxListingFallback(opening.selectedItem, lootboxId)
: []
const winner = opening && resolveLootboxSelectedItem(opening.selectedItem, possibleItems, opening.selectedItemId)
return (
<>
<button onClick={open} disabled={waiting}>Open</button>
{waiting && <YourOpeningAnimation />}
{winner && <YourRevealModal winner={winner} possibleItems={possibleItems} opening={opening} />}
</>
)
}pollUntil is yours: call the function every interval until it returns something, and give up at the timeout.
Four things to get right:
Poll, do not assume. The contents are not in the claim response. Poll the allocations until lootboxOpening.selectedItem appears.
Cap the wait. A timeout with a fallback message beats a spinner that never ends.
Show what was possible. The reveal lands harder next to what could have come out. useLootboxes returns the box's possible items. If that list comes back empty, buildLootboxListingFallback builds one from the winner so the reveal still has art.
Use the wait. An opening animation covering the poll turns latency into anticipation. Most partners overbuild the reveal and underbuild everything else, which for once is the right call.
When the item needs details
If the item a fan wins is a prize that needs an address or an email, there is a second claim, for the item itself. Every other win is delivered the moment the box opens.
Check before you offer it:
import { resolvePrizeClaimState, toSubmissionData, useClaimLootbox, usePrize } from '@xborglabs/fanbase-react'
const { data: prize } = usePrize(winner?.prizeId ?? '', Boolean(winner?.prizeId))
const { state: claimState } = resolvePrizeClaimState({ opening, prize })
const { claimLootbox } = useClaimLootbox()
if (claimState === 'REQUIREMENTS_REQUIRED') {
// show the details form, then:
await claimLootbox({ transactionId: opening.transactionId, opening, prize, submissionData: toSubmissionData(values) })
}Only REQUIREMENTS_REQUIRED allows it. For anything else, claimLootbox refuses without sending a request. That matters: claiming a win that was already delivered fails on the platform as a server error, indistinguishable from an outage. Letting the SDK check first means it never gets that far.
The loot box claim uses toSubmissionData, not the quest claim's builder. Different endpoint, different shape. Prizes and inventory covers every claim state.
Checklist
- Rewards render before completion, signed in or not
- Reward art and labels come from
resolveQuestRewardChrome, not a local map - An unknown reward type renders nothing rather than a broken card
fetchRewardsis on for the detail page, off for the list- A quest with two rewards ends with both claimed
- A prize needing an email collects it before the claim
- A loot box claim shows an animation, then the actual item, and has a timeout path
- A won prize that needs details offers its own claim, and nothing else does