Guild.xyz NFT/Token Roles Integration

Guild.xyz Integration (token-gated access)

Guild.xyz is a protocol for managing access based on on-chain conditions. Hold 100 project tokens — get a role in Discord. Own an NFT from a specific collection — join a private Telegram channel. The logic is verified automatically, without manual whitelisting.

Guild integration takes 1-3 days of development depending on condition complexity. Guild supports hundreds of conditions out of the box: ERC-20 balance, ERC-721 ownership, ERC-1155 balance, staking balances in popular protocols, Snapshot voting participation, POAP ownership.

Basic setup through Guild UI

Most use cases are solved through Guild's interface without a single line of code:

1. Create a Guild (tie it to a Discord server or Telegram)
2. Create a Role with conditions — for example: ERC-20 balance >= 500 [TOKEN_ADDRESS] on Ethereum
3. Guild provides an invite link — when users visit, they connect their wallet, Guild verifies the condition, and assigns the role

Supported platforms: Discord, Telegram, GitHub (repository access), Google Workspace (Drive access), Notion. For Discord — a separate Guild bot with role management permissions.

Custom conditions through Guild API

For non-standard criteria, Guild supports custom conditions through its own API endpoint.

// Guild Custom Contract Check
// Example: access only if user completed >= 5 transactions
// with a specific contract

// 1. Deploy a verification contract
contract ActivityChecker {
    mapping(address => uint256) public interactionCount;

    function checkEligibility(address user) external view returns (bool) {
        return interactionCount[user] >= 5;
    }
}

// 2. In Guild: condition type "CONTRACT" with ABI
// {
//   "type": "CONTRACT",
//   "chain": "ETHEREUM",
//   "address": "0x...",
//   "abi": [...],
//   "method": "checkEligibility",
//   "params": ["{user_address}"],
//   "returnIndex": 0,
//   "expected": true
// }

The placeholder {user_address} is automatically substituted by Guild during verification — the user's wallet being verified.

Compound conditions (AND/OR logic)

Guild supports compound conditions:

{
  "logic": "AND",
  "requirements": [
    {
      "type": "ERC20",
      "address": "0xTokenAddress",
      "chain": "POLYGON",
      "data": { "minAmount": "100" }
    },
    {
      "type": "ERC721",
      "address": "0xNFTAddress",
      "chain": "POLYGON"
    }
  ]
}

This covers most DAO use cases: "owns token AND has membership NFT", "met condition OR is an early participant".

Integration through Guild SDK

import { createGuildClient } from "@guildxyz/sdk";

const guild = createGuildClient("my-app-name");

// Create a role programmatically
const role = await guild.role.create(guildId, signer, {
  name: "Token Holder",
  requirements: [
    {
      type: "ERC20",
      chain: "ETHEREUM",
      address: tokenAddress,
      data: { minAmount: "1000" }
    }
  ]
});

// Check user eligibility
const access = await guild.user.getMemberships(userAddress);

The SDK is convenient for dynamic role management: a protocol can programmatically create or modify access conditions when tokenomics or milestones change.

Typical use cases

DAO contributor access: DAO members with sufficient governance token balance get access to private work channels on Discord.

NFT community: holders of an NFT collection automatically join a Telegram group without manual whitelisting.

Tiered benefits: different roles for different balance levels — Bronze (100+ tokens), Silver (1000+ tokens), Gold (10000+ tokens).

Cross-chain membership: condition is checked on multiple chains simultaneously — token on Ethereum OR NFT on Polygon.

Guild integration saves weeks of custom access control development. For most projects, this is the right choice — unless you need complete UX customization or to store membership data entirely on-chain.