How Guild works

Accounts, roles, requirements and how access is checked.

Guild checks members against the rules you set and keeps their access current. This page explains the moving parts: accounts, joining, requirements, roles and rewards, and how access is checked and re-checked.

Accounts and identities

People sign in to Guild with a wallet, an email address or a social account, and can add a second step with an authenticator app or a passkey; see Account security. One Guild account can then hold several connected wallets and accounts: wallets, X, Discord, Telegram, GitHub, Farcaster, email and others.

Requirements are checked against the accounts a member has connected. A requirement to follow an account on X needs a connected X account; a token requirement needs a connected wallet that holds the token. Members manage their connected accounts on their account page, and each guild shows which accounts its requirements check.

Connections belong to the member's Guild account, not to one guild. Connect a wallet once and every guild can check it.

Joining

A member joins a guild from its home page. Joining checks every role the guild offers and gives the member each role they already qualify for, with its rewards.

Most guilds are open to join. Some are invite-only or gated, and then the guild page offers no plain Join guild button.

Requirements, roles and rewards

Requirements are the conditions. They cover onchain activity (hold a token or NFT, make transactions, call a contract, hold a balance without a break), social accounts (follow on X, be in a Discord server, hold a Discord role), activity on Guild (hold another role, have enough points) and more. See Requirements for every type.

Roles are groups of people who meet a set of requirements. A role combines its requirements in one of these ways:

  • All of them must be met.
  • Any one of them is enough.
  • Some: at least a number you choose, for example any 2 of 5.

You can also split a role's requirements into groups and combine the groups the same way, for example "hold the NFT, or (follow on X and be in the Discord)". Some requirement types can be set to Should not satisfy, to keep people who meet them out.

Rewards are what a role unlocks: a Discord role, a Telegram group, points, a secret, an NFT, a form, or access to a page. See Rewards.

Example

  1. Create a role called "Token holders".
  2. Add a requirement: hold at least 500 of your token.
  3. Add rewards: a "Holder" Discord role and 5 points.
  4. A member with 500 tokens joins and gets the Discord role and the points.
  5. If they later drop below 500 tokens, they lose the role and, by default, the Discord role with it.

How access is checked

Access is checked on demand. When a member opens a guild, Guild reads their current access to its roles, and the role cards show each requirement as met, not met or not checked yet. A member can press Check access to re-run the check for a role, or for every role at once, at any time.

Guild also refreshes the data behind requirements in the background. A token sale, a new follower or a role earned elsewhere reaches Guild without anyone pressing a button, and access changes when the data does.

When data can't be read for a while, for example while it is being refreshed, Guild keeps the roles a member already has instead of taking them away. It never grants a role on missing data.

Gaining and losing roles

When a member starts meeting a role's requirements, they get the role and its rewards. When they stop meeting them, they lose the role, and its rewards are taken back: a Discord role is removed, and access to a gated page or Telegram group ends.

Some rewards let you choose what happens on loss. A Discord role reward has a Keep role once earned switch, and a points system can keep or deduct points when access is lost. See the reward pages for the details.

When a member loses a role, they get a Role removed notification. It is sent only after the loss has held for a while, so a brief blip in the data doesn't notify anyone.

Leaving a guild removes every role the member had in it, and their rewards. A kept Discord role is removed too.

All Guild docs