# What is Guild Guild is a tool that helps you grow and reward the right community members by tracking onchain and social activity. It manages access to Discord and Telegram, runs quests, and provides analytics to help you better understand your community. Guild connects your community across 60+ EVM chains and multiple platforms like Discord, Telegram, Twitter, GitHub, and more. Crypto projects use Guild for better community management. You see your members' wallet address(es) and their linked social accounts in one place, so you know who is an active onchain user and vocal supporter in your community channels. Projects usually use Guild to: * create token-gated communities * grow their community with quests * reward active and loyal supporters with Discord roles, NFTs, and tokens * analyze their whole community across platforms ### Why use Guild? Building your Guild is like building LEGO. Our platform is designed to be as flexible and customizable as building blocks, giving you the freedom to create and customize your community space based on your unique needs and preferences. Guild does both community building and quests. Most platforms focus on one or the other. Community platforms manage access but lack growth tools. Quest platforms run short campaigns but don't build lasting relationships. Guild combines both. You can build your core community with token-gating and member management. Then run quests and campaigns to grow that community. Your members stay engaged long-term while you attract new ones. Or do the opposite: grow through quests first, then create a more aligned group. Guild also helps you identify key community members, such as developers, and reward your most valuable contributors based on metrics that matter to you. Don’t struggle with multiple tools to build stronger communities. Just use one: Guild.
# How Guild works Guild organizes your community using three building blocks: Requirements, Roles, and Rewards. Think of it like a simple rule system: **Requirements** → What people need to do **Roles** → Groups you organize people into **Rewards** → What group members get
### Requirements Requirements are the conditions people must meet. These can be: * **Onchain activity** - Own $TOKEN/NFT, make 5 transactions on Ethereum, interact with XYZ smart contract * **Social proof** - Follow on X, hold Discord role “Member”, verify email * **Guild activity** - Have 50+ points, have XYZ guild role * **Time-based** - Have a Discord role before Jan 1st, have a transaction in the last 7 days on Base You can combine requirements with AND/OR logic. Example: "Hold $TOKEN AND Follow on X" or Hold $TOKEN OR Stake $TOKEN. Set “Should not satisfy” requirements to exclude people. ### Roles Roles are groups you create based on requirements. Examples: * Role: **Early Supporter** *role* - Requirements*:* Waitlist subscriber AND Genesis NFT holder * Role: **Active User** - Requirements: Have an interaction with the XYZ contract in the last 30 days AND hold a Discord role * Role: **OG Member** - Requirements: Have the “Early Supporter” AND the “Active Contributor” role AND Stake $TOKEN Members automatically gain or lose roles when they meet or stop meeting requirements. No manual management needed. ### Rewards Rewards are what role members get once they meet requirements. These include: * **Platform access** - Discord/Telegram groups, content, forms * **Digital rewards** - Points, NFTs and tokens * **Real perks** - Merchandise, event tickets, early access ### Example flow 1. Create role: "Token holders" 2. Set requirement: "Hold 500+ $TOKEN" 3. Add rewards: Token holder Discord role + 5 points 4. Members with 500+ tokens automatically get the Discord role and 5 points 5. If they sell tokens and drop below 500, they lose role & rewards automatically Set rules once. Guild handles everything else. # Main use cases ### 1. Token gating Control who accesses what based on wallet holdings. **How:** Set requirements like "Hold 100+ $TOKEN" or "Own Genesis NFT" to automatically gate access to Discord channels, Telegram groups, and more. **Examples:** * NFT projects gate holder-only Discord channels and exclusive drops * DeFi protocols gate channels and give special access for token holders/stakers only * Creators gate access to NFTs and content for collectors Members get automatic access when they qualify and lose it immediately when they sell or transfer tokens. Works across 60+ EVM chains including Ethereum, Base, and Arbitrum. No need to check wallets, update spreadsheets, or manually add/remove people. Guild checks onchain data 24/7 and updates access instantly. ### 2. Quests & campaigns Run quests where people complete tasks to earn rewards. **How:** Create multi-step quests combining onchain actions (make transactions, provide liquidity) with social tasks (follow on X, join Discord) and custom requirements. Track completion automatically and distribute rewards instantly or later. **Quest examples:** * **Onboarding quest:** "Follow on X + Join Discord + Interact with dApp" → Earn 10 points + Newcomer Discord role * **DeFi quest:** "Swap on DEX + Provide liquidity on ETH/$TOKEN pool " → Collect NFT reward + DeFi user Discord role * **Social quest:** "Like Tweet on X + Include ⛫ emoji in your X name + Join Telegram" → Earn 10 points + Social maxi Discord role * **Ecosystem quest:** "Bridge at least 0.001 ETH to Base + Use these dApps + Own a .base domain + Complete feedback form" → Collect NFT + Based member Discord role Create NFT rewards, set time limits and cap participation for exclusivity. Require previous quest completion, or create seasonal campaigns. Use different pages within your guild to keep it clean or for targeting specific groups, like developers. Quests are perfect for user acquisition, new product launches, and driving specific behaviors across your ecosystem. ### 3. Membership management & onboarding Create multiple roles for different purposes, group them into tiers, and guide new members through progressive onboarding. **How:** Build a complete member journey from newcomer to top contributor. Create specific roles for tracking onchain and social activities and organize them into simple tiers for easy management. Design onboarding flows that guide people toward earning these roles and ranking up. #### Create roles Build roles that onboard and recognize different types of community value: * **Newcomer:** Follow on X + Join Discord + Learn about the project * **App User:** First app interaction + Supply minimum $10 USDC * **Power User:** 20+ app interactions + Supply minimum $100 USDC + Stake 50+ $TOKEN * **Developer:** GitHub commits + Deploy contract * **Content Creator:** 5000+ X followers #### Group roles into tiers Organize your complex role system into simple tiers so members understand their status: **3-tier example:** * **Bronze:** Hold Guild roles + 10+ app interactions + Stake 10+ tokens * **Silver:** Hold Guild roles + First app interaction 6+ months ago + 50+ app interactions + Stake 50+ tokens * **Gold:** Hold Guild roles + First app interaction 1+ year ago + 100+ app interactions + Provide liquidity in the ETH/TOKEN pool + Stake 100+ tokens Members know their tier, what they've achieved, and what's next. You get simple community management despite complex underlying roles. Rewards can be Discord roles, exclusive NFTs, token airdrops, early product access, or custom perks. Members earn tiers when they qualify and lose them immediately when they no longer qualify. This approach is great for making complex community structures clearer and simpler. ### 4. Sybil protection Filter out fake accounts and bots using multiple verification layers. **How:** Use our Guild Citizenship feature to better filter out sybil accounts. Or simply combine different requirement types that are more difficult for bots to satisfy. Combine onchain verification (wallet age, balance), social proof (account age, minimum number of followers), and other credential checks, such as GitHub commits. **Protection strategies:** * **Guild Citizenship:** Require a minimum humanity score that members have to collect to prove their humanity * **Wallet verification:** Require wallets with a 6+ month history, transactions on Ethereum, and minimal wallet balances * **Social verification:** Require X & Discord accounts created before 2024 with a minimum of 100 X followers * **Other**: Require a minimum Gitcoin passport score or a Coinbase attestation that verifies a member’s verified account on Coinbase. It’s up to you how many and how strict the requirements you set. Guild helps you better filter out sybils and reward real valuable members of your community. # Launch your guild {% hint style="info" %} **Guild v2 is currently in open beta. You can launch your guild at** [**era.guild.xyz/create**](https://era.guild.xyz/create)**.** {% endhint %} Once your guild has been created, you can start customizing it to match your project and community needs. ### Customize your guild 1. **Access your admin dashboard:** * Click the settings icon (top right) to enter admin mode * This is your control center where you can customize your guild's appearance, structure, and view all guild details

Access your admin dashboard

2. **Brand your guild:** * Upload your logo (150x150px works best) * Edit the page title, URL, and description to introduce your project * Click **"Theme"** to upload a cover image (optimal size: 1920x1080px)
3. **Organize your content:** * Click **"Add page"** to create separate sections for campaigns, onboarding, or different community groups * Drag pages to reorder them in your preferred sequence * Each page can have its own focus, but keep your home page simple and clear since members will see this first
Customize guild pages

Customize guild pages

4. **Configure the basics:** * Go to the **Settings** tab in your admin dashboard * Edit your guild name and main URL (this becomes your permanent guild link) * Add your social media accounts (format: ) - these appear on your home page for easy discovery * Customize the appearance with surface and accent (button) colors that match your brand * Add admins to your guild **Test your setup:** Switch back to visitor mode to see what members will experience. # Add Guild roles ### Set up your first role Roles are how you control who gets what in your community. Each role can have different requirements to join and different rewards. #### Configure your default role **1. Access the role editor** * Go to the **"Editor"** tab in your admin dashboard * You'll see a default role called "Member" - this is your community's starting point
**2. Make it yours** * Upload a role image (128x128px works best) * Edit the role title and description to explain what this role is about * Keep it clear - this is often the first role people will see
**3. Set your requirements** * Click **"Add requirements"** to control who can access this role * Edit the requirement image and text, or keep the default settings * Common first requirements: Follow on Twitter, join Discord, or hold a specific token * Use **"Should not satisfy"** to exclude certain members * Adjust **"Should meet..."** at the top to decide if members need all requirements or just some
**4. Add rewards** * Click **"Add reward"** to give members something valuable * Popular rewards: Discord roles, NFTs, and points * Rewards activate automatically when members meet requirements
**5. Save and create more** * Save your changes to activate the role * Click **"Empty role"** below existing roles to create additional roles {% hint style="info" %} Most successful projects put their basic community roles - like Join Discord, Follow Twitter - on their home page, then create separate pages for campaigns or specialized subgroups like developers. {% endhint %}

Edit roles

#### Test and go live **Preview your work** * Use **"View page as a visitor"** to experience what members will see * Test that requirements work correctly and rewards claim properly * Make sure your messaging is clear and the flow is simple **Launch your community** * Once everything looks good, your Guild URL is ready to share Most projects begin with 2-5 key roles on their home page, then add membership tiers, quests, and specialized roles on new pages as their community grows. # How to add Discord Connect your Discord server to Guild so you can give members Discord roles as rewards and easily onboard your community. ### Connect Discord to your Guild **1. Add Guild bot to your Discord server** * Go to your role's rewards section and click **"Add reward"** * Select **Discord** from the reward options * Select which Discord server you want to connect (you must be an admin of that server to see it listed) * Click the **"Invite"** button in the popup and complete the authorization process * Return to adding a Discord reward and select your connected server * Create a new Discord role on Guild or Guildify an existing Discord role * Members can claim the Discord role automatically when they meet your requirements

Add Discord reward to your guild

**2. Set bot permissions** * **Important:** Move the Guild bot to the top of your Discord server's "Roles" tab (this ensures it can manage roles below it) * To manage bot permissions, go to the Guild bot and select **"Edit"** * The bot needs specific permissions to work properly: * **Must-have:** Manage Roles (required to give/remove Discord roles) * **Recommended:** Manage Server, Create Invite (helps with server management and invite creation) * **Good-to-have:** Manage Channels, Send Messages, Embed Links (needed for join buttons)
**3. Drive Discord members to Guild** * Create a **"get-roles"** channel on your Discord server * Write a description explaining what roles members can claim and why they should join * Share your Guild link (era.guild.xyz/YOURPROJECT) * Pin the message so it's always visible to new members {% hint style="info" %} Create Discord roles that match your Guild roles - like "Verified Member" or "Token Holder" - so the connection is clear. {% endhint %} #### How it works for members **Simple flow:** 1. Members can discover your Guild through Discord or find your Discord through Guild 2. They connect their Discord account to their Guild profile 3. They complete the requirements you've set 4. They automatically receive the Discord role 5. They gain access to gated channels and perks Most projects manage all their Discord roles through Guild. If you have existing Discord roles, you can connect them to Guild roles without creating new ones. # How to get verified Guild verification makes your guild visible and searchable on our platform for Guild users. {% hint style="warning" %} Verification is not a complete guarantee. Projects can change, and we cannot prevent all misuse of the platform. Always do your own research before participating in any community or claiming rewards. {% endhint %} ### Verification requirements * **Project authenticity** - We check verified social accounts (Twitter, Discord) and other public information to confirm the project is legitimate and established * **Complete guild setup** - Your guild must be fully built with roles, requirements, and rewards configured. We only verify guilds that are ready for public use * **Public launch** - Your project must be publicly announced on your official social channels Only project admins can request verification. ### How to request verification Send a DM on X (Twitter) to [@roland\_xyz](https://twitter.com/roland_xyz) with: * Your guild URL * Link to the public announcement of your guild launch If we already have a group chat, you can just request it there - no need to contact on X. We review each request individually and reserve the right to approve or reject applications without detailed explanation. We may revoke verified status at any time if projects change or issues arise. After your guild is verified, you will see a blue checkmark.

Verified Guild

{% hint style="info" %} If you encounter a suspicious guild, report it by creating a ticket through the message icon at the bottom right of our website. {% endhint %} # How to setup requirements Requirements are the conditions members must meet to access roles and their rewards. #### Setting up requirements **1. Add your first requirement** * In the role editor, click **"Add requirements"** * Choose from available requirement types * Provide the data needed for the requirement * Edit the requirement image and name, or leave empty to use default settings * Toggle **"Should not satisfy"** to exclude members who meet this requirement
**2. Configure requirement logic** * **"Should meet ALL"** - Members must satisfy every requirement (AND logic) * **"Should meet 1"** - Members need to satisfy at least one requirement (OR logic) * **"Should meet X out of Y"** - Members need to satisfy a specific number of requirements **3. Save and test** * Click **"Save"** * Use **"View page as a visitor"** to test the verification process #### How verification works for members: * Requirements are checked when members click **"Verify"** * If they haven't connected a required account, they will see a **"Connect Discord"** button (or Twitter, wallet, etc.) * Members can clearly see which requirements they have met and which they haven't {% hint style="info" %} Most requirements sync constantly - if someone stops meeting a requirement after getting the role, they automatically lose access. {% endhint %} #### Common mistake to avoid **Adding requirements to existing roles:** If you add new requirements to a role that members already have, all current members will lose access to that role since they likely don't meet the new requirement. Create a new role instead or notify members before making changes. # Allowlist An allowlist is a list of pre-approved wallet addresses or email addresses that grant access to specific roles. Perfect for exclusive launches, early access programs, or rewarding specific community members. #### Setting up your allowlist **1. Prepare your file** * Create a .txt or .csv file with one entry per line * **Wallet addresses:** Use EVM wallet addresses (e.g., 0x1234...) * **Email addresses:** Use standard email format () * **Mixed lists:** You can include both wallet addresses and emails in the same file
**2. Upload and configure** * In the role editor, click **"Add requirements"** and select **Allowlist** * Upload your .txt or .csv file * Name your allowlist to stay organized (e.g., "Early Testers", "Hackathon Winners 2024") * Optionally upload a custom image to visually identify the list * Click **"Add requirement"** You can update allowlists anytime by uploading a new file - changes apply immediately. Current role holders who get removed from the updated allowlist will lose access automatically. # Custom API call Check external APIs to verify member data or conditions not available on Guild. Perfect for integrating with custom databases, third-party services, or proprietary verification systems. #### Setting up Custom API Call requirements: * In the role editor, click **"Add requirements"** and select **Custom API Call** * Enter the **URL** of your API endpoint, including any path and query parameters * Use the literal template token `` anywhere you need to insert the user's wallet address: * Example: `https://my-api.com/wallets//balance` * When verified: Guild replaces `` with the actual wallet address like `0x123..` * If needed, add **Body of the request** - JSON data to send with your API call * If needed, add **Headers of the request** - Custom headers like authentication tokens or content types * Click **"+ Add more"** to include multiple headers * Select the **HTTP method** (GET, POST) * Set the **Key** - Specify which field in the API response to check (e.g., `status`, `verified`, `balance`) * Set the **Value** - Define what the response value should be (you can choose from equal, greater than, less than, etc.) * Add custom image and name for the requirement if you want * Click **"Add requirement"** {% hint style="danger" %} API calls made by Guild are public and can be reproduced by anyone with technical knowledge. Do not rely on this feature for sensitive data or assume the requests are private. {% endhint %} When members verify requirements, Guild calls your specified API endpoint and checks if the response contains the expected key-value pair. The member's wallet address is automatically inserted wherever you use ``. Please ensure your API endpoint can handle Guild's verification requests and returns consistent JSON responses. Consider rate limiting and authentication for security. # Discord ### Discord - Account Age Check when members created their Discord account to filter based on account age and reduce bot accounts. #### Setting up account age requirements **1. Configure the requirement** * In the role editor, click **"Add requirements"** and go to **Discord** * Choose **Account age** from the options * Select a date and choose your logic: * **On** - Account created exactly on this date * **After** - Account created after this date * **Before** - Account created before this date * **After or on / Before or on** - Include the exact date * Customize the requirement name and image if you want * Click **"Add requirement"** Members connect their Discord account and Guild automatically checks when they created it. *** ### Discord - Discord Member Check server-specific information like roles, nicknames, and membership duration for members in Discord servers. You don't need to be an admin on the server, but you must be a member. #### Setting up server member requirements **1. Configure the requirement** * In the role editor, click **"Add requirements"** and go to **Discord** * Choose **Discord member** from the options * First select which Discord server to check * Then choose what to verify: * **Role** - Member has a specific server role (most common) * **Nickname** - Member has a particular nickname set * **Server member since** - How long they've been in that server (uses same date logic as account age) * **Premium since** - When they got server premium (Nitro boosts) * Customize the requirement name and image if you want * Click **"Add requirement"** Members connect Discord and Guild checks their status in the specified server. They must be in the target server for verification to work. # EAS ### Ethereum Attestation Service Ethereum Attestation Service (EAS) is a decentralized protocol for creating and verifying attestations on Ethereum and other blockchains. Perfect for checking proof of attendance, certifications, memberships, or any verified credentials. #### **Configure the requirement** * In the role editor, click **"Add requirements"** and select **Ethereum Attestation Service** * Set the verification parameters: * **Chain** - Select the blockchain where the attestation is stored (e.g., Arbitrum, Base, Ethereum) * **Reference** - Wallet address of the attester (the person/entity who issued the attestation) * **Schema ID** - Unique identifier for the attestation (e.g., 0x1234...) * **Key** - The field name within the schema you want to verify (e.g., "rank", "status", "SelectionMethod") * **Value** - What that field must contain to qualify * Choose matching logic: * **Equal** - Value must match exactly * **Doesn't equal** - Value must be anything except what you specify * **Includes** - Value must contain the specified text or be part of a list * Customize the requirement name and image if you want * Click **"Add requirement"** Members connect their wallet and Guild automatically verifies their attestations on the specified blockchain. # Email Verify members have email addresses from specific domains. Perfect for gating access to employees, students, or verified community members from particular organizations. **Setting up email requirements:** * In the role editor, click **"Add requirements"** and select **Email** * Choose **Verify an email with a domain** * Enter the domain you want to check (e.g., guild.xyz, university.edu, company.com) * This matches against the domain part of the member's verified email address * Customize the requirement name and image if you want * Click **"Add requirement"** Members connect their email address and verify it through a confirmation link. Guild then automatically checks if the domain matches your requirements. # NFT Balance Check whether members hold specific NFTs or quantities of NFTs on a selected blockchain. Perfect for token-gated access, exclusive holder benefits, or tiered membership based on collection size. **Setting up NFT balance requirements:** * In the role editor, click **"Add requirements"** and select **NFT Balance** * Fill out the parameters: * **Chain** - Select the blockchain where the NFT contract is deployed * **Token address** - The contract address of the NFT collection you're checking * **Token ID** - Enter the unique identifier of a specific NFT, or leave blank to check general ownership of any NFT from this collection * **Balance** - Specify how many NFTs a member must hold using these conditions: * **Equal** - Must hold exactly the specified number * **Doesn't equal** - Must hold any number except the one specified * **Greater than** - Must hold more than the specified number * **Greater than or equal to** - Must hold at least the specified number * **Less than** - Must hold fewer than the specified number * **Less than or equal to** - Must hold at most the specified number * **Range** - Must hold a number within the specified range * Customize the requirement name and image if you want * Click **"Add requirement"** Members connect their wallet and Guild automatically checks their NFT holdings on the specified blockchain. If someone sells their NFT and no longer meets the requirement, they automatically lose access to the role. # Token balance Check whether members hold a certain amount of tokens on a selected blockchain. Perfect for creating token-gating access and tiered memberships. **Setting up token balance requirements:** * In the role editor, click **"Add requirements"** and select **Token Balance** * Fill out the parameters: * **Chain** - Select the blockchain where the token is deployed * **Token address** - The contract address of the token you want to check * **Balance** - Specify how many tokens members must hold using these conditions: * **Equal** - Must hold exactly the specified amount * **Doesn't equal** - Must hold any amount except the one specified * **Greater than** - Must hold more than the specified amount * **Greater than or equal to** - Must hold at least the specified amount * **Less than** - Must hold fewer than the specified amount * **Less than or equal to** - Must hold at most the specified amount * **Range** - Must hold an amount within the specified range * Customize the requirement name and image if you want * Click **"Add requirement"** Members connect their wallet and Guild automatically checks their token holdings. If someone sells their tokens and no longer meets the requirement, they automatically lose access to the role. # Contract query Check if a smart contract method returns specific values when called. Perfect for verifying custom onchain conditions, protocol holdings, or complex smart contract states. \ **Setting up Contract Query requirements:** * In the role editor, click **"Add requirements"** and select **Contract query** * Fill out the parameters: * Select the **Chain** where your contract is deployed * Enter the **Contract address** you want to query * Choose the contract **Method** from the dropdown (Guild automatically fetches available methods from the contract ABI) * Fill in the **Input parameters** - Guild shows the exact fields needed with names, types, and indexes * Select **Output to check** - choose which return value from the contract method to verify * **Output index** - Smart contract methods can return multiple values. The index (0, 1, 2, etc.) specifies which returned value to check: * Index 0 = first returned value * Index 1 = second returned value * Index 2 = third returned value, and so on \ \&#xNAN;*If a contract method returns `(uint256 balance, address owner, bool isActive)`, you would:* * *Use index 0 to check the balance (bigint)* * *Use index 1 to check the owner address* * *Use index 2 to check if it's active (boolean)* * **Output types:** * **Output bigint** - Large numbers (token balances, timestamps, counts, IDs) * **Output address** - Wallet addresses or contract addresses * **Output boolean** - True/false values (eligibility checks, status flags) * Add custom image and name for the requirement if you want * Click **"Add requirement"**
Members connect their wallet and Guild automatically calls the specified contract method with the configured parameters. If the contract returns the expected output value, the member qualifies for the role. # Farcaster Check Farcaster activity and profile attributes to gate access based on social engagement, profile completeness, or specific following relationships. #### Setting up Farcaster requirements **Have at least \[x] followers:** * In the role editor, click **"Add requirements"** and select **Farcaster** * Choose **Have at least \[x] followers** * Set the follower count condition using: * **Equal** - Exactly this number of followers * **Doesn't equal** - Any number except the one specified * **Greater than** - More than the specified number * **Greater than or equal to** - At least the specified number * **Less than** - Fewer than the specified number * **Less than or equal to** - At most the specified number **Follow a profile:** * Choose **Follow a profile** * Enter the **Target FID** of the account they must follow * Check the box if they must follow this account, or uncheck if they must NOT follow it **Have something in your profile:** * Choose **Have something in your profile** * Select which profile field to check: * **Bio** - Check if their bio contains specific text * **FID** - Check for a specific Farcaster ID * **Username** - Check for a specific username * **Display name** - Check for a specific display name * Choose matching logic: **Equal**, **Doesn't equal**, or **Includes** For all requirements, customize the requirement name and image if you want, then click **"Add requirement"**. Members connect their Farcaster account and Guild automatically verifies their profile data and social activity. # Github Verify GitHub activity and account properties to ensure members are active developers or meet specific contribution requirements. #### Setting up GitHub requirements **Star a repository:** * In the role editor, click **"Add requirements"** and go to **GitHub** * Choose **Star a repository** * Enter the **Repo ID** of the GitHub repository you want to track * Check the box if members must have starred the repo, or uncheck if they must NOT have starred it \ **Account age** * Choose **Account age** * Select a date and choose your logic: * **On** - Account created exactly on this date * **After** - Account created after this date * **Before** - Account created before this date * **After or on / Before or on** - Account created on or after/before the date \ **Commit count** * Choose **Commit count** * Set the commit count condition using: * **Equal** - Exactly this number of commits * **Doesn't equal** - Any number except the one specified * **Greater than** - More than the specified number * **Greater than or equal to** - At least the specified number * **Less than** - Fewer than the specified number * **Less than or equal to** - At most the specified number For all requirements, customize the requirement name and image if you want, then click **"Add requirement"**. Members connect their GitHub account and Guild automatically verifies their activity and account details. # Guild Check member activity and history directly within Guild. Perfect for role management, member progression, and participation-based access control. #### Setting up Guild requirements **Be a member of a guild:** * In the role editor, click **"Add requirements"** and go to **Guild** * Choose **Be a member of a guild** * Select which Guild you want to set as a requirement **Have a role:** * Choose **Have a role** * Select the guild and then choose the specific role within that guild **Have a reward:** * Choose **Have a reward** * Select the guild and then choose the specific reward the member must have claimed \ **Have connected an identity platform** * Choose **Have connected an identity platform** * Select which platform members must have connected to their Guild profile: * Discord * X * GitHub * Email * Farcaster * EVM wallet * Telegram **Be a Guild user since:** * Choose **Be a Guild user since** * Select a date and choose your logic: * **On** - Account created exactly on this date * **After** - Account created after this date * **Before** - Account created before this date * **After or on / Before or on** - Account created on or after/before the date For all requirements, customize the requirement name and image if you want, then click **"Add requirement"**. Guild automatically checks member data and platform connections to verify these requirements. # Guild Points Check whether members have collected a specific amount of Guild Points. Perfect for rewarding active participation, creating tiered access, or recognizing community contributions. #### Setting up Guild Points requirements * In the role editor, click **"Add requirements"** and select **Guild Points** * Select the right **Points** you want to check * Set the points amount condition using: * **Equal** - Exactly this number of points * **Doesn't equal** - Any number except the one specified * **Greater than** - More than the specified number * **Greater than or equal to** - At least the specified number * **Less than** - Fewer than the specified number * **Less than or equal to** - At most the specified number * **Range** - Any number within the specified range * Customize the requirement name and image if you want * Click **"Add requirement"** Guild automatically tracks and verifies member point balances. Points update in real-time as members earn them through various activities. # Telegram Check if members belong to specific Telegram groups or channels. **Setting up the Telegram requirement for groups:** * In the role editor, click **"Add requirements"** and select **Telegram** * Click **"Invite our bot to your group"** and select your group * Click **"Add bot as admin"** on Telegram (don't change permissions) * Once added, the Guild bot will send a message within the channel with the **Group ID** * Copy the **Group ID** of your Telegram group and paste it on Guild * Select what to check from the dropdown options * Add custom image and name for the requirement if you want * Click **"Add requirement"** \*You can add @guildxyz\_bot to your group directly on Telegram as well.
Add telegram requirement
**Setting up the Telegram requirement for channels:** * In the role editor, click **"Add requirements"** and select **Telegram** * Click **"Invite our bot to your channel"** and select your channel * Click **"Add bot as admin"** on Telegram (don't change permissions) * Once added, the Guild bot will send a message within the channel with the **Group ID** * Copy the **Group ID** of your Telegram channel and paste it on Guild * Select what to check from the dropdown options * Add custom image and name for the requirement if you want * Click **"Add requirement"** ### Required permissions If you added our bot through Guild, no action is needed. You only need to grant permissions if you manually added @guildxyz\_bot to your Telegram group or channel. **For groups,** add the bot as an admin with these permissions: * Ban users * Invite users via link **For channels,** add the bot as an admin with these permissions: * Ban users * Invite users via link * Post messages (required for channels) ### Channel limitations Telegram channels have some limitations compared to groups: * **No command menu** - When you type "/", the command list won't appear automatically; you have to type /start /help or /status and hit enter * **Bot must be admin** - The bot cannot see channel updates or respond unless it has admin permissions with "Post messages" enabled * **User experience** - You won't see available commands until the bot has proper admin permissions ### Bot commands You can use these commands in groups (channels have limited command visibility): * **/start** - Welcome message with Group ID and instructions * **/help** - View documentation and support links * **/status** - Check group status and configuration ### How it works for members Members connect their Telegram account and Guild automatically verifies their membership status and selected attributes in the specified group or channel. ### Important notes * **Your Telegram group must be set to "Private"** - You can change this in your group settings under Group Type * The bot status check includes verification that the group is set to private * The same bot (@guildxyz\_bot) is used for both requirements and rewards * If you previously used the old @guildxyz\_integration\_bot, it has been replaced by the unified @guildxyz\_bot # POAP Check if members own specific POAP (Proof of Attendance Protocol) NFTs. Perfect for verifying event attendance, community participation, or milestone achievements. **Setting up POAP requirements:** * In the role editor, click **"Add requirements"** and select **Attend** **POAP event** * Enter the **Event ID** of the POAP you want to check * Add custom image and name for the requirement if you want * Click **"Add requirement"** Members connect their wallet and Guild automatically checks if they own the specified POAP. \ POAPs are verified across all connected wallet addresses in their Guild profile. You can find POAP Event IDs on the POAP website or by checking the POAP's details on platforms like OpenSea. Use multiple POAP requirements to verify attendance at different events. # Visit link Check whether members have visited a specific URL. Perfect for ensuring members read important information, view announcements, or complete onboarding steps. **Setting up visit link requirements:** * In the role editor, click **"Add requirements"** and select **Visit link** * Enter the **URL** you want members to visit * Customize the requirement name and image if you want * Click **"Add requirement"** Guild tracks when members visit the specified link and automatically verifies this requirement. Members get immediate confirmation when they've successfully visited the required URL. # World ID profile Verify members' World ID credentials to ensure human verification and check specific profile attributes. Perfect for Sybil resistance and identity verification. **Setting up World ID Profile requirements:** * In the role editor, click **"Add requirements"** and select **World ID Profile** * Select what to check from the dropdown options: * **Given Name** - Verify the member's first name * **Family Name** - Verify the member's last name * **Verification Level** - Check the level of World ID verification * For Verification Level, choose from: * **Orb** - Highest verification level using Worldcoin orb scanning * **Device** - Device-based verification * **Document** - Document-based identity verification * **Secure Document** - Enhanced document verification with additional security * Add custom image and name for the requirement if you want * Click **"Add requirement"** Members connect their World ID and Guild automatically verifies the selected profile attributes. This ensures only verified humans can access roles while checking specific identity criteria. # X (Twitter) Check X profile activity and attributes to verify social engagement, account authenticity, or specific profile requirements. #### Setting up X requirements **Follow or be followed by:** * In the role editor, click **"Add requirements"** and select **X (Twitter)** * Choose **Follow or be followed by** * Enter the username of the account **Have something in your profile:** * Choose **Have something in your profile** * Select which profile attribute to check: * **Name** - Display name (not @username) * **Username** - The @handle of the account * **Description** - Bio/profile description text * **Verified** - Whether account has verification checkmark * **Protected** - Whether account is private * **Created at** - Account creation date * **Followers count** - Number of followers * **Following count** - Number of accounts they follow * **Tweet count** - Total tweets (including retweets) * **Like count** - Total tweets they've liked * **Listed count** - Number of public lists they're in * **Media count** - Number of media posts shared For all requirements, customize the requirement name and image if you want, then click **"Add requirement"**. Members connect their X account and Guild automatically verifies their profile data and social activity. # How to setup rewards Rewards are the benefits members receive when they qualify for roles. They are what makes your Guild valuable and give members clear incentives to engage with your community. ### Setting up rewards **1. Add your first reward** * In the role editor, click **"Add reward"** * Choose from available reward types (Discord, Telegram, NFT, Points) * Provide the configuration details needed for the reward type * Add more rewards if you want
**2. Save and test** * Click **"Save"** * Use **"View page as a visitor"** to see how rewards appear to members * Qualified members will automatically see available rewards ### How rewards work for members * Rewards are visible for all members but locked until requirements are met * Rewards become available to claim once the requirements are met * Members can claim rewards immediately by clicking the **"Claim"** button * Rewards are granted instantly, but assigning Discord roles can take time due to Discord rate limits (members see a time estimation for when the role will be assigned) * Members can see which rewards they have claimed
{% hint style="info" %} Most requirements sync automatically, so if someone stops meeting requirements and loses role access, they also lose reward access immediately. {% endhint %} ### Common mistake to avoid **Changing reward configurations:** If you remove/re-add a reward for an existing role, role members have to reclaim the rewards. # Discord role Grant Discord server roles automatically when members meet requirements. Perfect for creating tiered access, exclusive channels, and community recognition. #### Setting up Discord role rewards **1. Connect your Discord server** * In the role editor, click **"Add reward"** and select **Discord** * Select your Discord server from the already added server list * Or add a new one (see Discord setup guide: [How to add Discord](/guild/how-to-add-discord)) * Create a new Discord role or select an existing Discord role * Click **"Add reward"** {% hint style="info" %} The Guild bot must be on your selected Discord server to assign/remove roles. See how to add the Guild bot to your server here: [How to add Discord](/guild/how-to-add-discord). {% endhint %} #### How Discord role rewards work * Members see the Discord role reward but cannot claim it until they meet requirements * Once qualified, members click **"Claim"** to receive the Discord role * Role assignment happens automatically but may take 1-2 minutes due to Discord rate limits * Members see a timer showing estimated assignment time during busy periods * If members lose role access, the Discord role is automatically removed #### Requirements for setup * Guild bot must be added to your Discord server with "Manage Roles" permission * The Guild bot's role must be positioned higher than roles it needs to assign # Points Award customizable Guild Points to gamify participation, incentivize specific behaviors, and track member activity. Points accumulate over time and can unlock higher-tier roles or future rewards. #### Setting up Points rewards **1. Create your points system** * In the role editor, click **"Add reward"** and select **Points** * Give your points a custom name or just use "points" * Upload a custom icon to represent your points (optional) * Supported formats: PNG, JPG, SVG * Maximum file size: 5MB * Create the point system and set how many points members receive for qualifying for this role * Click **"Add reward"** * A leaderboard is automatically created for each point system {% hint style="info" %} You can create one point system across your whole Guild or multiple systems for different campaigns or member groups. {% endhint %} #### How Points rewards work for members * Members can claim points when they meet role requirements * On the leaderboard, they can see their total points and rank * You can use point totals as requirements for other roles to create progression systems * Points are off-chain and managed entirely within Guild #### Why use Points in your Guild * **Progression** - Let members accumulate experience and unlock higher roles over time * **Recognition** - Track and display meaningful contributions publicly * **Incentives** - Reward valuable actions like attending events or completing tasks * **Gamification** - Turn participation into an engaging experience with levels and tiers * **Future utility** - Use point balances for allowlists, exclusive drops, or real-world rewards # NFT reward Create and distribute custom NFTs to role members. Perfect for proof-of-participation, collectibles, community credentials, or exclusive access tokens with real onchain utility. #### Setting up NFT rewards **1. Create the NFT** * In the role editor, click **"Add reward"** and select **NFT** * Upload NFT image (JPG, PNG, or GIF, up to 100MB) * Add NFT name and metadata description (optional) * Set metadata attributes (rarity, level, season, etc.) - optional * Choose transferability: **Non-transferable (Soulbound)** or **Transferable**
**2. Configure supply and claiming** * Set supply: **Unlimited** or **Limited** with a maximum number * Set claim limits per wallet address * Configure claiming time window (start and end dates) * Choose supported blockchain from dropdown
**3. Set pricing and payout** * Set mint price or leave it zero for free minting * Configure payout address (defaults to your connected wallet) * Note: small Guild minting fee applies
**4. Deploy NFT** * Click **"Create NFT reward"** to deploy the contract onchain * Only members who meet the role's requirements can claim the NFT * Click **"Collect NFT"** to see contract details and top collectors {% hint style="info" %} Each NFT can only be attached to a single role. {% endhint %} #### How NFT rewards work for members * Members see the NFT reward but cannot claim until they meet role requirements * Once qualified, members click **"Collect NFT"** to mint the NFT to their wallet * Minting happens onchain and requires gas fees * NFTs appear in member wallets and automatically list on OpenSea * Metadata updates dynamically reflect on already minted NFTs Unlike other rewards, members keep their NFTs permanently even if they lose role access, since the NFT is already minted onchain.

Collect NFT page

# Telegram group Grant access to private Telegram groups automatically when members meet requirements. Perfect for gated communities, VIP channels, and holder-only discussions. #### **Setting up Telegram group/channel rewards:** * In the role editor, click **"Add reward"** and select **Telegram** * Click **"Add bot to group or channel"** and select your group/channel * Add the Guild bot as an admin (don't change permissions) * Once added, the Guild bot will send a message within the group with the **Group ID** * Copy the **Group ID** of your Telegram group and paste it on Guild * Click **"Add reward"** \*You can add @guildxyz\_bot to your group directly on Telegram as well. {% hint style="info" %} The Guild bot must have admin permissions in your Telegram group to automatically add and remove members. {% endhint %} #### How Telegram group rewards work for members * Members see the Telegram group reward but cannot join until they meet role requirements * Once qualified, members click **"Join group"** to get automatic access to the group * Access is granted immediately through the Guild bot * If members lose role access, they are automatically removed from the Telegram group #### Requirements for setup * You must be an admin of the Telegram group or channel you want to gate * The Guild bot must be added as an admin with proper permissions * Your Telegram group must be set to **"Private"** (you can change this in your group settings under Group Type) #### Bot commands for group management You can use these commands in groups (channels have limited command visibility): * **/start** - Welcome message with Group ID and instructions * **/help** - View documentation and support links * **/status** - Check group status and configuration #### Channel limitations When using Telegram channels as rewards: * **No command menu** - When you type "/", the command list won't appear automatically; you have to type /start /help or /status and hit enter * **Bot must be admin** - The bot needs admin permissions with "Post messages" enabled * **Setup required** - Make sure to add the bot through the "Add bot to channel" link, not the group link #### Important notes * The Guild bot (@guildxyz\_bot) handles both Telegram requirements and rewards * If you previously used separate bots, they have been unified into @guildxyz\_bot * The bot automatically manages member access based on role requirements - no manual intervention needed * Group ID is automatically provided in the welcome message when you add the bot * The bot status check verifies that your group is set to private and has proper permissions configured # Secrets Share hidden text, codes, or exclusive content that only qualified members can access. Perfect for coupon codes, private links, exclusive announcements, or special instructions. #### Setting up Secret rewards **1. Create the secret** * In the role editor, click **"Add reward"** and select **Secret** * Add a **Reward image & title** to represent your secret (e.g., "Secret Code", "Hidden Content") * Write your **Secret Text** using the rich text editor * Format your content with bold, italic, lists, and links as needed * Click **"Create Secret Reward"** #### How Secret rewards work for members * Members see the secret reward title and image but cannot view the content until they meet role requirements * Once qualified, members click **"Reveal Secret"** to access the hidden content * Secret content remains accessible as long as they maintain role eligibility * If members lose role access, they can no longer view the secret content # Case studies {% embed url="" fullWidth="false" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} # Welcome to Guild.xyz A summary of everything we've collected on our tools, live integrations, features and more. ### Welcome to the Guild.xyz Knowledge Base! #### Guides Get started with an overview of the Guild API & SDK, and voting.\ Click [here](https://help.guild.xyz/en/) for up-to-date guides and articles on guild creation and management, FAQs and more. #### Technical Find detailed information about our API, Query Engine and read the notes on our ZK research on the Privacy, Self-Sovereignty page. #### Links All the official platforms where you can connect with us. ![](/files/5rdJ0YKHeyOa2aGTotTu) \ ---------------------------------- # Guild for Developers API for automating token gated access in any applications. *Check out our SDK here:* [*https://www.npmjs.com/package/@guildxyz/sdk*](https://www.npmjs.com/package/@guildxyz/sdk) ## Guilds ## Create Guild `POST` `https://api.guild.xyz/v1/guild` #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="201: Created created guild" %} ```json { "id":2244, "name":"api-test", "urlName":"api-test", "description":"", "imageUrl":"/guildLogos/145.svg", "createdAt":"2022-03-09T17:28:52.153Z", "showMembers":true } ``` {% endtab %} {% tab title="400: Bad Request errors occurred" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} Guild is an atomic unit of every communities {% tabs %} {% tab title="Guild SDK" %} ```typescript import { guild, user } from "@guildxyz/sdk"; import { ethers } from "ethers"; // Creating a random wallet for the example const wallet = ethers.Wallet.createRandom(); // Wrapping the signer function from ethers.js const sign = (signableMessage: string | Bytes) => ethersWallet.signMessage(signableMessage); // Creating a Guild const myGuild = await guild.create( wallet.address, // You have to insert your own wallet here sign, { name: "My New Guild", description: "Cool stuff", // Optional imageUrl: "", // Optional theme: [{ mode: "DARK", color: "#000000" }], // Optional roles: [ { name: "My First Role", logic: "AND", requirements: [ { type: "ALLOWLIST", data: { addresses: [ "0xedd9C1954c77beDD8A2a524981e1ea08C7E484Be", "0x1b64230Ad5092A4ABeecE1a50Dc7e9e0F0280304", ], }, }, ], }, { name: "My Second Role", logic: "OR", requirements: [ { type: "ERC20", chain: "ETHEREUM", address: "0xf76d80200226ac250665139b9e435617e4ba55f9", data: { amount: 1, }, }, { type: "ERC721", chain: "ETHEREUM", address: "0x734AA2dac868218D2A5F9757f16f6f881265441C", data: { amount: 1, }, }, ], }, ], } ); ``` {% endtab %} {% tab title="API" %} ```json { "payload":{ "name": string, "imageUrl"?: string, "description"?: string, "roles": Role[], "theme"?: Theme[], "showMembers"?: boolean }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Get All Guilds `GET` `https://api.guild.xyz/v1/guild` {% tabs %} {% tab title="200: OK array of guilds" %} ```json [ { "id": number, "name": string, "roles": string[], // names of the roles "imageUrl": string, "urlName": string, "memberCount": number } ] ``` {% endtab %} {% tab title="204: No Content empty response, not found" %} **No Guild added.** {% endtab %} {% endtabs %} ## Check User Access to a Guild `GET` `https://api.guild.xyz/v1/guild/access/:id/:address` The response is separated by role identifiers. #### Path Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------- | | id\* | number | id of the guild | | address\* | string | address of the user | {% tabs %} {% tab title="200: OK array of accesses" %} ```json [ { "roleId":2339, "access":true }, { "roleId":2015, "access":true }, { "roleId":99, "access":false } ] ``` {% endtab %} {% tab title="400: Bad Request errors occured" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="500: Internal Server Error errors occurred, but response still available" %} ```json [ { "roleId":2540, "access":true }, { "roleId":2560, "access":null, "errors":[ { "requirementId":5861, "msg":"Multicall received an empty response. Check your call configuration for errors." } ] }, { "roleId":2537, "access":false }, { "roleId":2538, "access":false } ] ``` {% endtab %} {% endtabs %} ## Get User `GET` `https://api.guild.xyz/v1/guild/member/:id/:address` #### Path Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------- | | id\* | number | id of the guild | | address\* | string | address of the user | {% tabs %} {% tab title="200: OK " %} ```json [ { "roleId":1034, "access":false }, { "roleId":1031, "access":false }, { "roleId":1175, "access":true } ] ``` {% endtab %} {% tab title="400: Bad Request errors occurred" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} ## Get Guilds Joined by a User `GET` `https://api.guild.xyz/v1/user/membership/:address` #### Path Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------- | | address\* | string | address of the user | {% tabs %} {% tab title="200: OK " %} ```javascript [ { "guildId":13, "roleids":[ 397 ] }, { "guildId":21, "roleids":[ 1175 ] }, { "guildId":1533, "roleids":[ 2339, 2015 ] }, ] ``` {% endtab %} {% tab title="400: Bad Request errors occurred" %} ```javascript { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} ## Join a Guild `POST` `https://api.guild.xyz/v1/user/join` #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="200: OK " %} ```javascript [ ] ``` {% endtab %} {% tab title="400: Bad Request errors occurred" %} ```javascript { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```javascript { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Guild SDK" %} ```typescript import { user } from "@guildxyz/sdk"; import { ethers } from "ethers"; // Joining to a Guild if any role is accessible by the given address await user.join( guildId, // Insert Guild ID here walletAddress, // Your wallet address signerFunction); // Your lib's signing method ``` {% endtab %} {% tab title="API" %} ```json { "payload": { "guildId": number }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Get a Guild by ID `GET` `https://api.guild.xyz/v1/guild/:id` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ----------------------- | | id\* | string | id/urlName of the guild | {% tabs %} {% tab title="200: OK guild object" %} ```json { "id": number, "name": string, "urlName": string, "description": string, "imageUrl": string, "showMembers": boolean, "admins": [ { "id": number, "address": string, "isOwner": boolean }, ], "theme": { "mode": "DARK" | "LIGHT", "color": string, "backgroundCss": string, "backgroundImage": string }, "platforms": [ { "id": number, "platformId": string, "type": "DISCORD" | "TELEGRAM", "platformName": string, } ], "roles": [ { "id": number, "name": string, "description": string, "imageUrl": string, "logic": "AND" | "OR" | "NAND" | "NOR", "requirements": Requirement[], "members": string[], // array of addresses "memberCoun": number, } ] } ``` {% endtab %} {% tab title="204: No Content empty response, not found" %} **Specified Guild doesn't exist with the given ID or urlName.** {% endtab %} {% endtabs %} Guild ID could be a number or an urlName of a guild. ## Update Guild `PATCH` `https://api.guild.xyz/v1/guild/:id` #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="200: OK array of accesses to roles" %} ```json /// ``` {% endtab %} {% tab title="400: Bad Request errors occurred" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} **Automate new role creation, manage hundreds of roles and update them on the fly.** A few examples where this could be useful: 1. Extend an allow list automatically. 2. Users can invite others by adding their address to an allow list. {% tabs %} {% tab title="Guild SDK" %} ```typescript import { guild } from "@guildxyz/sdk"; import { ethers } from "ethers"; await guild.update( guildId, // Insert Guild ID here walletAddress, // Your wallet address signerFunction, // Your lib's signing method updateGuildParams); // Params ``` {% endtab %} {% tab title="API" %} ```json { "payload":{ "name": string, "imageUrl": string, "description": string, "roles": Role[], "theme": Theme[], "showMembers": boolean }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Delete Guild `DELETE` `https://api.guild.xyz/v1/guild/:id` #### Path Parameters | Name | Type | Description | | ---------------------------------- | ------ | ----------- | | \* | number | | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="200: OK " %} ```json { "success": boolean } ``` {% endtab %} {% tab title="400: Bad Request errors occured" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Guild SDK" %} ```typescript import { guild } from "@guildxyz/sdk"; import { ethers } from "ethers"; await guild.delete( guildId, // Insert Guild ID here walletAddress, // Your wallet address signerFunction); // Your lib's signing method ``` {% endtab %} {% tab title="API" %} ```json { "payload":{ // Empty object is necessary }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Roles ## Get Role `GET` `https://api.guild.xyz/v1/role/:id` #### Path Parameters | Name | Type | Description | | ---------------------------------- | ------ | ----------- | | \* | number | | {% tabs %} {% tab title="200: OK " %} ```json { "imageUrl":"/guildLogos/107.svg", "name":"Member", "description":"", "logic":"AND", "requirements":[ { "type":"ERC20", "address":"0x1b6c5864375b34af3ff5bd2e5f40bc425b4a8d79", "alue":"1", "chain":"ETHEREUM" } ], } ``` {% endtab %} {% tab title="204: No Content " %} **Specified Role doesn't exist with the given ID.** {% endtab %} {% endtabs %} Roles are the building-blocks of all guilds. You can create as many as you want to distinguish users by certain conditions. Each role can represent a membership type, grant temporary or permanent access to content in your application. Common use-cases include: 1. **Membership tiers** 2. **Clubs** 3. **Permission management for work collaboration.** 4. **Access** to articles. 5. **Ticket** to a virtual event or IRL. 6. **Special privileges** in a social application. ## Create Role `POST` `https://api.guild.xyz/v1/role` #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="201: Created Created Role" %} ```json { "imageUrl":"/guildLogos/107.svg", "name":"Member", "description":"", "logic":"AND", "requirements":[ { "type":"ERC20", "address":"0x1b6c5864375b34af3ff5bd2e5f40bc425b4a8d79", "value":"1", "chain":"ETHEREUM" } ] } ``` {% endtab %} {% tab title="400: Bad Request errors occured" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} To create a new role, you need to define its requirements and the logic type of stacking these requirements. {% tabs %} {% tab title="Guild SDK" %} ```typescript import { role } from "@guildxyz/sdk"; import { ethers } from "ethers"; await role.create( walletAddress, // Your wallet address signerFunction, // Your lib's signing method { guildId: 1, // Insert Guild ID here name: "My Third Role", logic: "AND", requirements: [ { type: "ALLOWLIST", data: { addresses: [ "0xedd9C1954c77beDD8A2a524981e1ea08C7E484Be", ], }, }, ], }); ``` {% endtab %} {% tab title="API" %} ```json { "payload":{ "name": string, "imageUrl"?: string, "description"?: string, "logic": "AND" | "OR" | "NAND" | "NOR", "requirements": Requirement[] }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Update Role `PATCH` `https://api.guild.xyz/v1/role/:id` #### Path Parameters | Name | Type | Description | | ---------------------------------- | ------ | ----------- | | \* | number | | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="200: OK " %} ```javascript { // Response } ``` {% endtab %} {% tab title="400: Bad Request errors occured" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} You can update roles anytime, but be aware that existing members might loose access to their guild if the requirements change. Updating roles programatically is a powerful way to manage communities with dynamic membership requirements or keep requirements up-to-date automatically. {% tabs %} {% tab title="Guild SDK" %} ```typescript import { role } from "@guildxyz/sdk"; import { ethers } from "ethers"; await role.update( roleId, // Insert Role ID here walletAddress, // Your wallet address signerFunction, // Your lib's signing method updateGuildParams); // Params ``` {% endtab %} {% tab title="API" %} ```json { "payload":{ "name": string, "imageUrl": string, "description": string, "logic":"AND" | "OR" | "NAND" | "NOR", "requirements": Requirement[] }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Delete Role `DELETE` `https://api.guild.xyz/v1/role/:id` #### Path Parameters | Name | Type | Description | | ---------------------------------- | ------ | ----------- | | \* | number | | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | payload\* | Object | | | validation\* | Object | | {% tabs %} {% tab title="200: OK " %} ```javascript { "success": boolean } ``` {% endtab %} {% tab title="400: Bad Request errors occured" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% tab title="401: Unauthorized authentication required" %} ```json { "errors": [ { "msg": string } ] } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Guild SDK" %} ```typescript import { role } from "@guildxyz/sdk"; import { ethers } from "ethers"; await role.delete( guildId, // Insert Guild ID here walletAddress, // Your wallet address signerFunction); // Your lib's signing method ``` {% endtab %} {% tab title="API" %} ```json { "payload":{ // Empty object is necessary }, "validation": { // Validation object } } ``` {% endtab %} {% endtabs %} ## Requirements Guild enables requirement creation based on standard contract types and integrated protocols. ### COIN Native fungible tokens of supported blockchains. ```json { "type": "COIN", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI, FANTOM, AVALANCHE, ARBITRUM, HARMONY "data": { "amount": number // floating point number } } ``` ### ERC-20 Commonly referred to as tokens. ```json { "type": "ERC20", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI, FANTOM, AVALANCHE, ARBITRUM, HARMONY "address": string, // contract address "data": { "amount": number // floating point number } } ``` ### ERC-721 or ERC-1155 Commonly referred to as NFTs. ```json { "type": "ERC721" | "ERC1155", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI, FANTOM, AVALANCHE, ARBITRUM, HARMONY "address": string, // contract address "data": { "id": number, // tokenId (optional) "amount": number, // integer, number of NFTs to hold, "attribute": { // required attribute of the NFT (optional) "trait_type": string, // key of the attribute "value": string // value of the attribute "interval": {"min": number, "max": number} // interval of the attribute } } } ``` ### [POAP](https://poap.xyz) NFTs issued by the Proof of Attendance Protocol (POAP) represent special shared memories. ```json { "type": "POAP", "data": { "id": string // fancy_id of the POAP } } ``` ### [MIRROR](https://mirror.xyz) NFTs minted on Mirror.xyz, the web3-native publishing platform. ```json { "type": "MIRROR", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI, FANTOM, AVALANCHE, ARBITRUM, HARMONY "address": string, // constract address "data": { "id": number // ediotion id, TODO: how do we know the edition number } } ``` ### [UNLOCK](https://unlock-protocol.com) Membership NFTs issued by the Unlock Protocol. ```json { "type": "UNLOCK", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI "address": string, // contract address "data": { "amount": number } } ``` ### [SNAPSHOT](https://github.com/snapshot-labs/snapshot-strategies/tree/master/src/strategies) STRATEGIES Snapshot strategies are JavaScript functions that return a score for a set of addresses. They are being used on Guild to enable any custom condition check. Currently available strategies: Learn how to create a new strategy: ```json { "type": "SNAPSHOT", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI, FANTOM, AVALANCHE, ARBITRUM, HARMONY "data": { "startegy": object // strategy object, e.g. in https://github.com/snapshot-labs/snapshot-strategies/blob/master/src/strategies/aave-governance-power/examples.json } } ``` ### [JUICEBOX](https://juicebox.money/#/) Tokens created with Juicebox protocol, so communities can utilize their tokens while they are still staked. ```json { "type": "JUICEBOX", "chain": string, // supported chains: ETHEREUM, BSC, POLYGON, XDAI, FANTOM, AVALANCHE, ARBITRUM, HARMONY "data": { "id": number, // id of the project, "amount": number // minimum amount staked } } ``` ### ALLOWLIST Allow lists, commonly referred to as "whitelists" enable curation based on a list of wallet addresses collected from an external source. ```json { "type": "ALLOWLIST", "data": { "addresses": string[] // the allowed user addresses } } ``` ### FREE Guest pass for guild members without any requirements. ```json { "type": "FREE" } ``` # Example Guilds ### Protocol DAO {% embed url="" %} {% embed url="" %} ### Venture DAO {% embed url="" %} ### Gaming DAO {% embed url="" %} {% embed url="" %} ### Service DAO {% embed url="" %} ### NFT Community {% embed url="" %} {% embed url="" %} # Guild Query Engine An app for querying tokens on any EVM compatible chain. # Privacy, Self-Sovereignty Notes on ZK research at Guild.xyz (WIP) [0xPARC](https://0xparc.org/about) (Program for Applied Research in Cryptography) is actively developing methods to prove public key derivation from secret keys, verifying ECDSA signatures, etc. in zk snarks. They use [circom](https://docs.circom.io/) for this which is a fairly low level language for writing zk snark circuits. Problem is, that these circuits contain millions of constraints and require a significant amount of computational resources (tens of gigabytes of RAM). [`StealthDrop`](https://github.com/stealthdrop/stealthdrop) is a prototype implementation making use of such circuits. We are looking for alternative solutions (more lightweight) to prove that someone has the corresponding private key for a given public key **without** disclosing their public key. So far, [ring signatures](https://en.wikipedia.org/wiki/Ring_signature) are quite promising, as our usecase is exactly that we need to prove that we are part of a group of addresses that hold some kind of tokens. Through [Balancy](https://github.com/zgendao/balancy) we are able to construct such address groups publicly. An entry-level (mathematical) introduction of how ring signatures work can be found in [Monero's handbook](https://www.getmonero.org/library/Zero-to-Monero-2-0-0.pdf). There is a [Rust repo](https://github.com/edwinhere/nazgul) that implements the math in this handbook which helped constructing our prototype. There are some further practical issues to solve though. `StealthDrop` uses [ECDSA verification circom scripts](https://github.com/0xPARC/circom-ecdsa) that are way more bulkier than just proving secret/public key derivation because there's no way to extract the bare private key from a wallet like Metamask. You can read an interesting twitter thread about this [here](https://twitter.com/0xPARC/status/1493704577002049537?s=20\&t=X-5Bs1oWNjmbTASp2T82DA). Ring signatures also make use of direct access to the secret key when generating the proof. However, [there might exist a solution](https://github.com/cloudflare/zkp-ecdsa) where EDCSA signature verification happens via masking the public key via Pedersen commitments. The whitepaper describing the algorithm can be found [here](https://eprint.iacr.org/2021/1183.pdf), and it builds on [Groth's seminal paper](https://eprint.iacr.org/2014/764.pdf). The advantage of this method is that it doesn't seem to require direct access to the user's private key. Thus, the user only signs a message (using Metamask for example), commits a Pedersen commitment masking their public key and generates the proof based on these values. #### Proposed flow * I. Balancy generates a list of eligible (Ethereum) addresses for a given guild. * II. Users whose address is found in this array (ring) may provide a ring signature that proves they are eligible to enter the guild. * III. The guild backend receives the ring signature (proof) along with the ID of the guild and (Discord) ID of the user and verifies the proof.