Run a points program and leaderboard

Create a points system, award points through roles, grant or import adjustments, show a leaderboard and export it as CSV.

To run a points program with a leaderboard on Guild, create a points system in your guild's admin Points module, then add a points reward to the roles you want to reward. Members earn the points when they qualify for a role and claim its reward, and every points system has its own leaderboard. Admins can also grant or deduct points by hand, import adjustments from a CSV, and export the leaderboard as a CSV. Points systems, points rewards, the leaderboard and manual adjustments are available on the Free plan. Leaderboard exports and points through the REST API need the Pro plan or above.

How points work on Guild

  • A points system is a named balance, such as "XP" or "Guild Points". Each one has its own balances, leaderboard and transaction history. A guild can run one system or several, for example one per season or campaign.
  • Points rewards attach a system to a role. When a member gets the role, they can claim its points from the role's reward card.
  • Adjustments are grants and deductions made by an admin, from your own code or by an agent, outside any role.
  • Every change is a new entry in a ledger. A deduction is a negative entry, so the history behind each balance stays complete.

Because a member claims a role's points once, roles are best for one-off milestones: joining or reaching a tier. For tasks such as "repost this on X" that pay points during a campaign, use a quest: its points are paid only between its start and end dates. For points that accrue again and again, such as weekly activity in your app, use adjustments, the CSV import or the REST API.

Set it up

  1. Create a guild if you don't have one yet, and open its admin panel.
  2. Under Modules, open Points and press Create points system (New points system once you have one). Enter a Point Name, for example "XP", and optionally an icon.
  3. Press Settings on the system to choose its visibility: Public (visible to members) or Hidden (visible to admins only). Only a public system has a member-facing leaderboard.
  4. In Settings, under Balance behavior, decide what happens to points When user loses role access, When user leaves guild and When reward is deleted. The defaults are Keep, Deduct and Keep. Each reward can override them.
  5. Open Spaces & roles, select a role, and under Unlocks press Add reward. Pick Points, pick your system, and choose Static for a fixed amount or Dynamic for an amount calculated from the member's native coin balance on an EVM chain, multiplied by a rate you set. Press Add reward.
  6. Repeat for each role that should give points. The role's requirements decide what earns them: holding a token, onchain activity, following on X, a Discord role, holding another role, and more.

To turn points into progression, add a points requirement to higher roles, for example a role that needs at least 500 XP.

Grant, deduct and import points

On the Points page, press Adjust points. Choose Grant or Deduct, find the Member by name or paste their Guild user ID, enter the amount, and add an optional Reason, which appears in the transaction history. Review the adjustment and confirm it.

For many changes at once, open the menu next to Settings and choose Import adjustments. Paste CSV rows of Guild user ID, whole-number amount and an optional note, for example userId,amount,note. Positive amounts grant points and negative amounts deduct them. Each row becomes its own transaction, up to 500 rows per import, and you review every row before it is recorded.

Admin grants and deductions, including imports, are recorded in the guild's Audit log. To reset a season, Settings has Reset or delete this system: a reset adds correction entries that bring every balance to zero, and keeps the system, its rewards and its history.

The leaderboard

The Points page has two views. Leaderboard ranks accounts with a positive balance. History lists every grant, deduction and reward claim, and can be filtered to one member. Leaderboard figures can take up to five minutes to refresh.

For a public system, the menu has Open public leaderboard, a page members can visit at guild.xyz/<your-guild>/leaderboard/<system-id>. Members see their balance and rank there. The guild page also lists their balance in every public system under Your points, with their rank for the main system only. Choose Use as main system on the public system that should show the rank.

This leaderboard counts every point of the system since it was created. For a leaderboard over a fixed window, such as the 30 days of a campaign with prizes for the top 10, create a quest leaderboard: it counts only the points earned between its start and end, and its CSV export is built for reviewing and paying winners. See Leaderboards and prizes.

Under Settings, the Member tiers tab adds named thresholds, such as Contributor at 100 and Champion at 500, shown as badges next to balances. Tiers are display labels only: they don't grant roles or rewards. Use a points requirement for that.

Export and automate

On the leaderboard, press Export CSV to download the highest balances, up to 10,000 accounts. The file has each Guild user ID and point balance, and you can add one Additional identity column: Discord, X, GitHub, email, EVM wallet, Telegram, Google or Farcaster. Exports are a Pro plan feature.

From your own code, the REST API can grant or deduct points and read balances and the leaderboard. API keys need the Pro plan or above. An AI agent connected through the Guild MCP server can read balances and the points ledger with the Member data permission, and grant or deduct points with the Moderation permission. The MCP server is in beta and free on every plan.

FAQ

Can members earn points for the same role more than once? No. A member claims a role's points once. If the points were deducted, for example because they lost the role, they can claim them again when they qualify again.

Do members lose points when they sell their tokens or leave? By default, points are kept when a member loses a role and deducted when they leave the guild. You can change both in the system's Balance behavior, and override them per reward.

Can I give points for activity outside Guild? Yes. Grant them with Adjust points, import a CSV, or send them from your own code through the REST API.

Can I hide the leaderboard? Yes. Set the points system to Hidden and only admins can see its balances and leaderboard.

What does it cost? Points systems, points rewards, the leaderboard and admin adjustments work on the Free plan. CSV exports of the leaderboard and points through the REST API need Pro ($99 a month) or above. See Plans.

All Guild docs