🏅Open Quest & Leaderboard

An open quest and leaderboard to track users participating within your platform


Projects wanted their users to perform task with gamified activities in exchange of points that can be converted to rewards within their app and community. At the same time provide transparency to the community on how leaderboards are ranked without centralized control. Since we are launching our app templates with some tapper/clicker micro games, these leaderboards are essentials to make this possible to award points based on completed quest items by users.

Transparent Community Building

This leaderboard allows to transparently showcase your growth number by tracking participating users for any implementing app wether from Xircus deployed apps or outside our platform. We are providing a GraphQL API endpoint where you can request these collected data for any future use. Take note that these leaderboard only collects authenticated wallet addresses and a randomly generated username, no other personal information requested. These data can be exported via CSV or JSON format by leaderboard owner only.

On-Chain and Off-Chain Verification

What's unique about these quests is that they were fully integrated with web2 and web3 verification mechanism to verify users real activity from different platforms and TON based transactions and contract operations.

  • On-Chain -> users transactions are verified wether from having token balances, processing a contract operation or simple transfer call

  • Off-Chain -> user participation are verified from joining and interacting with platforms as part of the quest like following a twitter account, joining telegram, participating in mini apps and more

Multi-App Implementation

Each quest can be implemented by any Xircus powered web3 app wether Telegram Mini App or TON Web App so there's no need to create new quest for each app they can just share the same resources specially if you have deployed multiple connecting apps. For example, a marketplace app that tells people to launch NFTs in auction app and stake JETTONs in a staking app.

Gamified Quest Items

Each quest item has varying point value which is added up to the user points on completion which boost their standing in the leaderboard ranking and to unlock levels and badges

The Leaderboard Explorer

Explore any public visible leaderboards who implemented our Leaderboard SDK or built-in leaderboard UI components in deployed TON web apps and Telegram Mini apps

User Flow

  • Join Quest

  • Complete Item Tasks

  • Rank In Leaderboard

Use Cases

  • A Collection Drop Campaign -> Create a quest for your upcoming NFT launch, let users participate and complete all quest item tasks to be part of the allowlist or whitelist. Those users in the top 3 of your leaderboard gets to mint for free, from 3 to 25 gets 50% discount, and 25 onwards gets 10% discount

  • A Marketplace Campaign -> Create a quest for your marketplace where users receives points when they deploy their collection, mint their nfts and list them in your marketplace contracts

  • An Auction Campaign -> Create a quest for your upcoming token auction that let users earn points by sharing and hyping your token in different social platforms to boost engagements and interest in your upcoming sale

Quest Activity Types

  • Invite / Referral -> sharing an invite link

  • Link -> opening a link

  • Login -> hourly or daily login

  • Prompt -> answering a question

  • Telegram Join -> joining telegram

  • Twitter Follow -> following a twitter account

  • Twitter Share

  • Deploy Telegram Mini App

  • Deploy TON Web3 App

  • Deploy Collection

  • Deploy Jetton

  • Mint NFT

  • Mint SBT

  • Deposit Supply

Quest Components

  • Max Allocated Points are maximum allowed points to be given

  • Schedule contains the start time and end time of a quest

  • Allowlist contains the user addresses that are allowed to join

  • Items are the quest tasks with configurable conditions

  • Badges are claimable based on consistency on X task

  • Levels are claimable based on total points earned

  • Ranks are assignable or given by app owner to any account

DUST UI Blocks (dust-common)



List all users who joined the quest and rank them based on points and latest activity

Quest ID


Displays all quest created for the app



Displays the info of the quest including total users, total points awarded, total points available and

Quest ID (Props or Query)

Quest Create

Displays a form to create the basic info of the quest

Quest Edit

Displays a form to modify the current quest info, items, badges, levels, ranks

Quest ID (Props or Query)

Quest Account

Displays the quest journey and stats of the current account or specific account or wallet address

Quest ID Account ID or Address

Quests Admin (Editing Panel)

Displays all quests created by the current admin

Quest Item Properties

  • Repeatability or recurrence -> this is how often the item can be accomplished by the account. For example, Daily, Weekly or Monthly

  • Max Claim Limit -> this the number of times an item can be awarded to an account

  • Required Level -> these are item types that are locked until the account reaches a certain level

  • Verification -> there are item types that requires on-chain or off-chain verification. For example, following a twitter account, requires to verify if a certain twitter account followed the requested account

  • Mystery Type -> these items will only unlock if they are completed (TBA)

React Hooks

yarn add @xircus-web3/ton-react

How to use
import { useQuest } from "@xircus-web3/ton-react"
const { quest } = useQuest(QUEST_ID)

useLeaderboard (questId)

Returns the list of users that is ranked based on points and recent activity Ability to extract to CSV or JSON (Admin Only)

useQuest (questId)

Returns the quest info update -> Ability to update all details (Admin Only) assignTo -> Ability to assign to any app allowlist -> Ability to add allowlist

useQuestAccount (questId, appId)

Returns the current status of an account including points, rank, level and others join -> Ability to join award -> Ability to do task by awarding to account verify -> Ability to verify quest item claimLevel -> Ability to claim level (if not awarded) claimBadge -> Ability to claim badge (if not awarded) claimRank -> Ability to claim rank (if not awarded) claimReward -> Ability to claim reward


Returns all quests created by current account as admin create -> Ability to create new quest setVisibility -> Ability to toggle quest visibility to public or private assignTo -> Ability to assign to any app

useAppQuests (appId)

Returns all quests that are associated to an app unassign -> Ability to remove association of an app restrict -> Ability to prevent quests to associate the app (TBA)


Returns all public quests created from Xircus Studio

Last updated