Quests

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:

SlugWhat the fan getsAfter the claim
give_resourcesXP or currency. The most common reward by volume.Credited. Show the amount.
give_resources_progressiveThe same, at a fixed amount that does not shrinkCredited
give_assetsAn inventory itemIn their inventory
give_prizesA prize. May need an email or an address first.Granted, then shipped if physical
give_lootboxesA loot boxThe reveal
give_personalizationsA cosmetic: a profile picture, border or backgroundReady to equip
assign_discord_roleA role in your DiscordAssigned on Discord
manual_claim_rewardSomething your team hands over by handNothing 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.

A decaying rewardTry it
Starting value
100
Drop per claim
2
Floor
20
Fans who claimed first
15
This fan gets
70 XP
Hits the floor after
40 claims
20100First claimClaim 60
It falls with each claim, not with time. A quiet quest stays near its starting value for days. Example values, in XP.

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:

claimStatusdistributionStatusMeansShow
ALLOCATEDALLOCATEDWaiting to be claimedThe claim button
CLAIMEDALLOCATEDClaimed, still being deliveredProcessing
CLAIMEDDISTRIBUTEDThe fan has itDone

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.

Opening a loot boxTry it
Server
Result
What could come out
🪙 250 Coins55%
🖼️ Profile border30%
👕 Signed shirt15%
Claiming opens the box. What it holds is decided then, and lands a moment later.
Polls every 0.7s. A real timeout would be about 20s; this one gives up after 8 polls. Example odds.

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
  • fetchRewards is 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

On this page