Guild for Developers

API for automating token gated access in any applications.

Check out our SDK here: 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

{
   "id":2244,
   "name":"api-test",
   "urlName":"api-test",
   "description":"",
   "imageUrl":"/guildLogos/145.svg",
   "createdAt":"2022-03-09T17:28:52.153Z",
   "showMembers":true
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

Guild is an atomic unit of every communities

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,
            },
          },
        ],
      },
    ],
  }
);

{
   "payload":{
      "name": string,
      "imageUrl"?: string,
      "description"?: string,
      "roles": Role[],
      "theme"?: Theme[],
      "showMembers"?: boolean
   },
   "validation": {
      // Validation object
   }
}

Get All Guilds

GET https://api.guild.xyz/v1/guild

[
    {
        "id": number,
        "name": string,
        "roles": string[], // names of the roles
        "imageUrl": string,
        "urlName": string,
        "memberCount": number
    }
]

No Guild added.

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

[
   {
      "roleId":2339,
      "access":true
   },
   {
      "roleId":2015,
      "access":true
   },
   {
      "roleId":99,
      "access":false
   }
]

{
    "errors": [
        {
            "msg": string
        }
    ]
}

[
   {
      "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
   }
]

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

   [
      {
         "roleId":1034,
         "access":false
      },
      {
         "roleId":1031,
         "access":false
      },
      {
         "roleId":1175,
         "access":true
      }
   ]

{
    "errors": [
        {
            "msg": string
        }
    ]
}

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

[
   {
      "guildId":13,
      "roleids":[
         397
      ]
   },
   {
      "guildId":21,
      "roleids":[
         1175
      ]
   },
   {
      "guildId":1533,
      "roleids":[
         2339,
         2015
      ]
   },
]

{
    "errors": [
        {
            "msg": string
        }
    ]
}

Join a Guild

POST https://api.guild.xyz/v1/user/join

Request Body

Name

Type

Description

payload*

Object

validation*

Object

[

]

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

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

{
      "payload": {
            "guildId": number
      },
      "validation": {
      // Validation object
      }
}

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

{
    "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,
                
                }
    ]       
}

Specified Guild doesn't exist with the given ID or urlName.

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

///

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

Automate new role creation, manage hundreds of roles and update them on the fly.

A few examples where this could be useful:

Extend an allow list automatically.
Users can invite others by adding their address to an allow list.

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

{
   "payload":{
      "name": string,
      "imageUrl": string,
      "description": string,
      "roles": Role[],
      "theme": Theme[],
      "showMembers": boolean
   },
   "validation": {
        // Validation object
   }
}

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

{
    "success": boolean
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

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

{
   "payload":{
      // Empty object is necessary
   },
   "validation": {
      // Validation object
   }
}

Roles

Get Role

GET https://api.guild.xyz/v1/role/:id

Path Parameters

Name

Type

Description

number

{
   "imageUrl":"/guildLogos/107.svg",
   "name":"Member",
   "description":"",
   "logic":"AND",
   "requirements":[
      {
         "type":"ERC20",
         "address":"0x1b6c5864375b34af3ff5bd2e5f40bc425b4a8d79",
         "alue":"1",
         "chain":"ETHEREUM"
      }
   ],
   }

Specified Role doesn't exist with the given ID.

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:

Membership tiers
Clubs
Permission management for work collaboration.
Access to articles.
Ticket to a virtual event or IRL.
Special privileges in a social application.

Create Role

POST https://api.guild.xyz/v1/role

Request Body

Name

Type

Description

payload*

Object

validation*

Object

{
   "imageUrl":"/guildLogos/107.svg",
   "name":"Member",
   "description":"",
   "logic":"AND",
   "requirements":[
      {
         "type":"ERC20",
         "address":"0x1b6c5864375b34af3ff5bd2e5f40bc425b4a8d79",
         "value":"1",
         "chain":"ETHEREUM"
      }
   ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

To create a new role, you need to define its requirements and the logic type of stacking these requirements.

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",
              ],
            },
          },
        ],
      });

{
   "payload":{
      "name": string,
      "imageUrl"?: string,
      "description"?: string,
      "logic": "AND" | "OR" | "NAND" | "NOR",
      "requirements": Requirement[]
   },
   "validation": {
      // Validation object
   }
}

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

{
    // Response
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

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.

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

{
   "payload":{
      "name": string,
      "imageUrl": string,
      "description": string,
      "logic":"AND" | "OR" | "NAND" | "NOR",
      "requirements": Requirement[]
   },
   "validation": {
      // Validation object
   }
}

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

{
    "success": boolean
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

{
    "errors": [
        {
            "msg": string
        }
    ]
}

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

{
   "payload":{
      // Empty object is necessary
   },
   "validation": {
      // Validation object
   }
}

Requirements

Guild enables requirement creation based on standard contract types and integrated protocols.

COIN

Native fungible tokens of supported blockchains.

{
    "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.

{
    "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.

{
    "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

NFTs issued by the Proof of Attendance Protocol (POAP) represent special shared memories.

{
    "type": "POAP",
    "data": {
        "id": string // fancy_id of the POAP
    }
}

MIRROR

NFTs minted on Mirror.xyz, the web3-native publishing platform.

{
    "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

Membership NFTs issued by the Unlock Protocol.

{
    "type": "UNLOCK",
    "chain": string,   // supported chains: ETHEREUM, BSC, POLYGON, XDAI
    "address": string, // contract address
    "data": {
        "amount": number
    }
}

SNAPSHOT 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: https://github.com/snapshot-labs/snapshot-strategies/tree/master/src/strategies

Learn how to create a new strategy: https://docs.snapshot.org/strategies/create

{
    "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

Tokens created with Juicebox protocol, so communities can utilize their tokens while they are still staked.

{
    "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.

{
    "type": "ALLOWLIST",
    "data": {
        "addresses": string[] // the allowed user addresses
    }
}

FREE

Guest pass for guild members without any requirements.

{
    "type": "FREE"
}

Last updated 1 year ago

Was this helpful?