Roles for NFT holders

Give NFT holders roles by collection, number held or token ID, sum several wallets, cover staked NFTs, and have Guild take access away when an NFT is sold or moved.

To give NFT holders roles with Guild, make one role per kind of holder and give each an NFT Balance requirement: at least 1 from your collection for a holder role, a higher balance for each tier, or a list of token IDs for owners of specific pieces. Each role unlocks a Discord role, a Telegram group or a gated page. Guild checks every wallet a member has connected, refreshes holdings in the background, and takes the role and its rewards away when someone sells or moves the NFT. NFT requirements work on 50 EVM mainnets and are part of the free plan.

For step-by-step setup, see Token-gate a Discord server and Token-gate a Telegram group.

The building blocks

  • Holder role: NFT Balance, your collection, at least 1. Leave the token ID empty so any NFT from the collection counts.
  • Tiers by number held: one role per tier, each with its own balance, for example at least 1, at least 5 and at least 20. Tiers stack: a member with 20 NFTs holds all three. For tiers that don't overlap, add a second NFT Balance requirement to the lower tier with Less than the next threshold, and set Members should meet to All.
  • Specific pieces: enter one Token ID, or switch to Multiple Token IDs and paste a list, such as the first 100 IDs of a genesis drop.
  • Several collections: each requirement checks one contract on one chain. Add one per collection and combine them with Any one (hold any of them), All (hold one of each) or Some (for example 2 of 3).
  • Long-term holders: Held continuously for checks that a wallet never dropped below the balance for a number of days, and Held at a past block checks a snapshot. Both work on Ethereum and Base only. See Holding history.

Guild checks collections and token IDs, not traits or other metadata. If you want a role for a trait, look up which token IDs carry it and paste them as Multiple Token IDs.

Multiple wallets

One Guild account can hold several connected wallets, and Guild checks all of them. By default one wallet must hold enough on its own. Tick Sum across connected wallets on an NFT requirement to add up all of a member's wallets, which matters for tiers: a collector with 3 NFTs in one wallet and 2 in another reaches a "5 or more" tier only with the sum.

Keeping roles correct after sales and transfers

Guild refreshes onchain data in the background, so a sale or transfer reaches Guild without anyone pressing a button. When a member's balance falls below a requirement, they lose the role, and what can be taken back goes with it: the Discord role is removed, the bot removes them from the Telegram group and gated pages close. A member who buys in can press Check access to be checked right away.

Decide for each reward what should happen on a sale:

  • For access, leave Keep role once earned off on the Discord reward, so the role follows the NFT.
  • For recognition that should outlast a sale, such as "Mint day holder", switch Keep role once earned on, or give an NFT reward members mint for themselves; a minted NFT stays in their wallet.
  • Points are kept by default when a role is lost. Each points system can deduct them instead. See Points and leaderboards.

If Guild temporarily can't read a member's data, it keeps their roles rather than taking them away.

Staked and delegated NFTs

An NFT Balance requirement counts what a wallet holds. If your staking contract takes custody of the NFT, the wallet no longer holds it and the requirement isn't met. If the staking contract has a read function that answers per wallet, such as balanceOf(address), a Contract query can check it with USER_ADDRESS as the input. Put the two in one role with Any one, so holding or staking is enough.

Guild has no built-in support for delegation registries. A member who keeps NFTs in a separate wallet connects that wallet to their Guild account instead.

Example: a collection on Base

Role Who gets it Unlocks
Holder Any one of: NFT Balance, your collection on Base, at least 1; Contract query balanceOf(address) on your staking contract, output greater than 0 "Holder" Discord role, the holders' Telegram group
Collector NFT Balance, same collection, at least 5, Sum across connected wallets ticked "Collector" Discord role, a gated "Collectors" page
Genesis NFT Balance, Multiple Token IDs 1 to 100, at least 1 "Genesis" Discord role, a Secret with the link to a private call

Staking sits inside the Holder role, not a second role, so one Guild role owns the "Holder" Discord role.

Put the gated page behind the Collector role under Who can see it, with Role holders. See Gate pages, forms and secret content.

Example: rewarding loyalty on Ethereum

  • OG holder: Held continuously for, ERC721, your collection on Ethereum, 365 days, at least 1. Unlocks an "OG" Discord role with Keep role once earned off, so it stays meaningful.
  • Mint day: Held at a past block, the block your mint closed, at least 1. Unlocks a soulbound NFT badge (Non-transferable), which stays with the member after a sale.

FAQ

Can Guild gate by NFT traits?

No. Guild checks the collection and token IDs, not metadata. Use Multiple Token IDs with the IDs that have the trait.

Do members lose their Discord role when they sell?

Yes, once Guild's refreshed data shows the drop, unless Keep role once earned is on for that reward.

Does Guild support Solana or other non-EVM NFTs?

No. Onchain requirements work on EVM chains. See Supported chains.

Can I hide a tier from people who don't hold it?

Yes. Set the role's Who can see it to Secret or Hidden (Starter plan and above) or Self-reveal (Pro and above). See Plans.

All Guild docs