GuildPass SDK

The official TypeScript SDK for the GuildPass protocol.

Features • Installation • Quick Start • Documentation • Development • Contributing

---

Part of the Adamantine-Guild project — a Web3 membership and token-gated community platform for the open-source ecosystem.

🛡️ About GuildPass

GuildPass is a Web3 membership and access-control protocol designed for token-gated communities, guilds, dashboards, and ecosystem integrations. This SDK provides a production-grade interface for developers to build secure, gated experiences in both Node.js and Browser environments.

✨ Features

• 🛡️ Access Control: Check wallet access for resources and roles with ease.
• 💎 Membership Management: Verify active membership status and user roles.
• 🏗️ Guild Configuration: Fetch metadata and custom configurations for any guild.
• ⚡ Pluggable Caching: Built-in TTL cache with optional custom adapter support (Redis, etc.).
• 🧩 Modular Architecture: Clean service-based design for minimal bundle size.
• 💪 Type Safe: First-class TypeScript support with comprehensive definitions.
• 🌐 Universal: Seamless integration with Node.js, modern browsers, and Edge runtimes.

📦 Installation

# Using pnpm (recommended)
pnpm add @guildpass/sdk

# Using npm
npm install @guildpass/sdk

# Using yarn
yarn add @guildpass/sdk

🚀 Quick Start

Initialize the client and check access in seconds.

import { GuildPassClient } from '@guildpass/sdk';

// 1. Initialize the client
const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  chainId: 8453, // Base Mainnet
});

// 2. Perform an access check
const result = await client.access.checkAccess({
  walletAddress: '0x1234...5678',
  guildId: 'prime-guild',
  resourceId: 'premium-docs',
});

if (result.hasAccess) {
  console.log('✅ Access Granted');
} else {
  console.log(`❌ Denied: ${result.reason}`);
}

🛠️ Service Modules

The SDK is organized into focused service modules accessible via the main client:

Module	Purpose
client.access	Handle resource gating and role-based access checks.
client.membership	Query wallet membership status and join dates.
client.roles	Retrieve available roles and user assignments.
client.guilds	Fetch guild metadata, themes, and social links.
client.contracts	Resolve chain config and read on-chain GuildPass contract data.

⚙️ Configuration

const client = new GuildPassClient({
  apiUrl: string;           // Base API endpoint
  chainId?: number;         // Default chain (default: 1)
  apiKey?: string;          // Optional API key for restricted access
  validateResponses?: boolean; // Validate response shapes at runtime (default: false)
  cache?: CacheAdapter;         // Optional cache adapter (see Caching section below)
  cacheTtl?: number;            // Default TTL in ms for all cached entries
  rpcUrl?: string;          // Optional RPC provider for on-chain checks
  contractAddress?: string; // Optional default contract address
  chains?: Record<number, { // Optional per-chain RPC/contract overrides
    rpcUrl?: string;
    contractAddress?: string;
  }>;
});

⚡ Caching

Passing a cache adapter enables transparent memoization of all read operations (access checks, membership, roles, guild metadata). The public API of every service method is unchanged — caching is completely invisible to callers.

Built-in: InMemoryCacheAdapter

import { GuildPassClient, InMemoryCacheAdapter } from '@guildpass/sdk';

const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  cache: new InMemoryCacheAdapter(),
  cacheTtl: 60_000, // entries expire after 60 s
});

// First call hits the network; subsequent calls with the same arguments return
// the cached response instantly.
const guild = await client.guilds.getGuild({ guildId: 'prime-guild' });

Custom adapter (e.g. Redis)

Implement the CacheAdapter interface and pass it in:

import { CacheAdapter } from '@guildpass/sdk';
import { createClient } from 'redis';

const redis = createClient();
await redis.connect();

const redisAdapter: CacheAdapter = {
  async get<T>(key: string): Promise<T | null> {
    const raw = await redis.get(key);
    return raw ? (JSON.parse(raw) as T) : null;
  },
  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
    const opts = ttl ? { PX: ttl } : undefined;
    await redis.set(key, JSON.stringify(value), opts);
  },
  async delete(key: string): Promise<void> {
    await redis.del(key);
  },
  async clear(): Promise<void> {
    await redis.flushDb();
  },
};

const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  cache: redisAdapter,
  cacheTtl: 30_000,
});

Cache invalidation

// Evict all entries tied to a specific guild (e.g. after an admin change).
await client.invalidateGuildCache('prime-guild');

// Evict all wallet-scoped entries.
await client.invalidateWalletCache('0x1234...5678');

// Full wipe.
await client.clearCache();

Membership token balances

Configure rpcUrl and contractAddress to query the configured membership token:

const client = new GuildPassClient({
  apiUrl: 'https://api.guildpass.xyz',
  rpcUrl: 'https://mainnet.base.org',
  contractAddress: '0x0000000000000000000000000000000000000000',
});

const balance = await client.contracts.getMembershipTokenBalance({
  walletAddress: '0x1234567890123456789012345678901234567890',
});

The lookup uses an eth_call against balanceOf(address) and returns the raw token balance as a decimal string.

📚 Documentation

For more detailed guides and API references, check out:

• Architecture Overview
• SDK Usage Guide
• Full API Reference
• Integration Guide

🏗️ Development

# Install dependencies
pnpm install

# Build for production (tsup)
pnpm build

# Watch mode for development
pnpm dev

# Run unit tests (watch)
pnpm test

# Run tests once (CI mode)
pnpm test:run

# Lint
pnpm lint

# Format
pnpm format

# Type checking
pnpm typecheck

# Generate TypeDoc API docs
pnpm docs

🗺️ Roadmap

• On-chain Support: Native integration with viem and ethers.
• Auth: Wallet signature verification (SIWE) helpers.
• React: Official @guildpass/react hooks package.

🤝 Contributing

We welcome contributions from the community! See CONTRIBUTING.md for the full guide.

1. Browse open issues tagged good first issue or help wanted.
2. Comment on the GitHub issue you'd like to work on.
3. Fork the repo, create a feature branch, implement your change, open a PR.

Maintainer contact

• Contact: cerealboxx123@gmail.com

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Built with ❤️ by the GuildPass team

guildpass.xyz