Awesome Circles

A curated list of resources for the Circles ecosystem - a decentralized, trust-based currency on Gnosis Chain where every human mints 1 CRC per hour.

Circles is a personal-money protocol: every account issues its own currency, balances decay 7% per year (demurrage), and value flows along trust edges. Group currencies wrap personal CRC into fungible community money, and a network-wide pathfinder routes transitive-trust payments.

Contents

• Glossary
• Start Here
• Build a Mini App
• Wallets & Apps
• Mini Apps
  • Consumer Mini Apps
  • Group & Admin Tools
  • Developer Demos
• Protocol & Architecture
• Developer Tools
• Explorers & Indexers
• Pathfinders
• SDKs & Libraries
• APIs & Infrastructure
• Starter Kits & Tutorials
• For AI Agents
• Research, Simulation & Reputation
• Hackathon Projects
• Background Reading
• Community
• Contribute

Glossary

Term	Meaning
CRC	The currency unit. Every human avatar mints 1 CRC per hour.
Avatar	A Circles account. Three kinds: human, group, organization.
Trust	A directional edge: "I accept your CRC at 1:1." Makes a token transferable to strangers.
Group currency	A fungible ERC-20 backed by a basket of members' personal CRC - one shared money for a community.
Demurrage	The 7%/year balance decay. Money you don't use shrinks; the point is to keep CRC circulating.
Pathfinder	Service that finds a chain of trust edges to route a payment from A to B (transitive trust).

Start Here

• Circles World - Earn CRC by inviting friends, create a group, build an app, or host an event.
• Circles World - Mini Apps - Browse the live mini-app gallery from any Gnosis App wallet.
• About Circles homepage - Manifesto, whitepaper, FAQ, and ecosystem overview.
• How Circles Works - Personal currencies, group currencies, trust, and demurrage in one page.
• Introducing Circles v2 - The v2 launch announcement on the Gnosis blog explaining design rationale.

Build a Mini App

The fastest builder path. A mini app is a small web app that loads inside the Circles host and signs through the user's Safe via postMessage. Embedded mini apps ship from the official registry; standalone mini apps run anywhere and approve transactions via QR or deep link.

• What are Circles Mini Apps - Embedded vs standalone, when to pick which.
• Embedded Mini App guide - Build a mini app that ships inside the official store.
• Intermediate Embedded guide - Advanced patterns for embedded apps.
• Standalone Mini App guide - Run anywhere, sign via QR or deep link.
• Contribute a Mini App - Slug, code at src/routes/apps/<slug>/, logo, miniapps.json entry, PR.
• Mini Apps Launchpad - Rolling bounties: $500 App of the Week, $1,000 Winner of the Month.
• CirclesMiniapps repo - The host SvelteKit app and the registry. Submit PRs here.
• oic_apps - Open Internet Club mini-app framework: metadata-driven configs, QR-code payments, real-time Circles RPC event monitoring.

Wallets & Apps

• Metri - The official Circles v2 wallet. Passkey login, Safe smart account, fiat on/off-ramps via CoW Swap, and real-world spending via Gnosis Pay.
• Gnosis App - Gnosis super-app that hosts Circles accounts, invite links, and the Mini App store.
• Gnosis Pay - Visa-compatible card that lets you spend CRC and other Gnosis Chain assets at any merchant.

Mini Apps

Live examples to study and remix. See Build a Mini App above for the docs.

Consumer Mini Apps

• Coinflip Game - Bet 1 CRC on heads or tails; the reference embedded mini app.
• XMTP Demo - End-to-end encrypted DMs and group chat between Circles accounts via XMTP.
• Merch Shop - Reference checkout flow for selling merch in CRC.

Group & Admin Tools

• Invitations Manager - Mint, share, and track Circles invite links from one dashboard.
• Circles Groups - Create and manage group currencies and their member trust sets.
• Group Liquidity Bootstrapper - Spin up an LBP to seed liquidity for a group currency on Gnosis Chain.
• MiniApps Builders Org Manager - Manage builder-org accounts that ship mini apps.
• Test Account Flag - Mark an avatar as a test account so it doesn't pollute ecosystem analytics.

Developer Demos

• Sign Message Demo - Minimal example of requesting a signature via the Mini App postMessage protocol.
• ERC20 Transfer Demo - Minimal example of requesting a wallet transaction.

Protocol & Architecture

Deployed on Gnosis Chain.

• Circles Architecture Overview - Hub V2, vaults, treasury, mint policies, and name registry on one diagram.
• circles-contracts-v2 - Solidity source for the Hub V2 (ERC-1155), Migration contract, Name Registry, Standard Treasury, Vaults, and Base Mint Policy.
• circles-groups - Reference group-template contracts (membership conditions, custom mint policies).
• circles-social-recovery - Foundry contracts for a Safe SocialRecoveryModule letting GApp users recover passkey access via human guardians.
• Personal Currencies - Per-avatar minting, demurrage math, and the rule of trust.
• Group Currencies - How communities pool personal CRC into a fungible group token.

Developer Tools

• CirclesTools - Hub of browser utilities: Profile Checker, Group Checker / Creator / Manager, Trust Graph & Trust Path Visualizers, Personal CRC Replenisher, Circles Backing dApp, LBP Starter, Token Distribution Checker, Safe State & Tx Hash Checker, Equilibrium Analysis, Onboarding Helper, and Legacy Safe Creator.
• Pathfinder App - Compute and visualize optimal transfer routes through the trust network.
• CirclesTools source - Repository for the tools hub.
• flow-visualization - Source for the pathfinder flow visualizer.
• group-tms - Trust-Management Service: keeps a group's trust set in sync with declarative conditions.
• Developer Tools docs - Annotated index of every tool in the hub.

Explorers & Indexers

• circles-explorer - Block-explorer-style UI for Circles transactions, events, humans, groups, and orgs.
• profile-service - Stores and retrieves avatar profile metadata via IPFS.

Pathfinders

Routing engines that turn the trust graph into transfer paths.

• pathfinder - Original Circles pathfinder.
• pathfinder2 - Rewrite in Rust, used by the production pathfinder service.
• pyfinder - Python pathfinder implementation.
• pathfinder-proxy - Proxy layer in front of the pathfinder RPC.

SDKs & Libraries

• @aboutcircles/sdk - Current TypeScript SDK. Simplified surface over avatars, trust, pathfinding, profiles, and Safe execution. Published as @aboutcircles/sdk on npm.
• circles-rs - Rust workspace mirroring the TS SDK: RPC client, pathfinder, flow-matrix, transfer planning, and a higher-level circles-sdk crate.
• circles-sdk (legacy) - Earlier full-surface TypeScript SDK. Still referenced by many existing tutorials.
• @aboutcircles/sdk-core - Low-level contract bindings for Hub V2.
• @aboutcircles/sdk-rpc - Typed client for the Circles JSON-RPC methods.
• @aboutcircles/sdk-pathfinder - Pathfinder client used by the SDK.
• @aboutcircles/sdk-profiles - Read and write avatar profile metadata.
• @aboutcircles/sdk-runner - Execute operations through a Safe smart account.
• @aboutcircles/sdk-transfers - Build transfer payloads from pathfinder output.
• @aboutcircles/sdk-types - Shared TypeScript types.
• @aboutcircles/sdk-utils - Demurrage math and helpers.
• 5ecret-garden - Circles Marketplace monorepo: circles-market-sdk, auth, cart, catalog, orders, offers, and profile packages plus a SvelteKit app.
• SDK Reference - Full method and event surface for the current SDK.

APIs & Infrastructure

• Circles JSON-RPC - https://rpc.aboutcircles.com/. Public RPC: circles_query, circlesV2_findPath, circlesV2_getTotalBalance, circles_events, and more.
• Pathfinder Service - Optimal routing through the trust graph, available via SDK or raw RPC.
• Circles Indexer / Query - SQL-style queries over indexed avatars, trust edges, balances, and transfers.
• circles-nethermind-plugin - Nethermind execution-client plugin that exposes the Circles RPC namespace from a self-hosted node.
• circles-spaceneth - Standalone Nethermind node bundled with indexer and contracts for local testing.
• crc-faucet - CRC faucet for testnets / demos.
• circles-migration-tool - Tooling for migrating accounts and balances from v1 to v2.
• invite-api - Express/TypeScript HTTP API for issuing and auditing Circles invitations, with optional Slack webhook integration.
• marketplace-api - Product-catalog aggregator and order API for the Circles Marketplace.
• Avatar event subscriptions - Stream balance, trust, and group events in real time.

Starter Kits & Tutorials

• circles-gnosisApp-starter-kit - Official TypeScript starter for Gnosis × Circles apps.
• circles-dev-kit - Guided, hands-on tour of the Circles SDK.
• Circles-starter-kit - Hacker guide for developers to learn Circles and build projects.
• circles-vite-app - Vite playground for both Circles v1 and v2.
• mycircles - Third-party SvelteKit reference combining @aboutcircles/sdk, Auth.js, and Safe protocol-kit for profile and trust management.
• SDK Quickstart - Install, connect a wallet, and mint your first CRC.
• Setting up the SDK with React + JavaScript - End-to-end React integration.
• Gnosis App Starter Kit Tutorial - Walkthrough of the official starter.
• Vibecoding a Standalone Mini App - Ship a standalone mini app with no protocol expertise.

For AI Agents

Resources that help coding agents (Claude Code, Cursor, Codex, Windsurf) write Circles code that compiles against the current SDK instead of hallucinating deprecated APIs.

• Agentic Setup for Circles - Official guide: install Context7 MCP, point your agent at the aboutcircles/circles-docs and aboutcircles/sdk libraries, drop a CLAUDE.md / .cursorrules in the project root.
• llms.txt - Compact index of the docs, formatted for LLM ingestion.
• llms-full.txt - Full doc corpus in one file. Paste into a prompt or fetch from an agent.
• Doc query endpoint - GET https://docs.aboutcircles.com/<path>.md?ask=<question> returns an answer grounded in that page. Works for any doc page.
• Sitemap - Machine-readable index of every doc URL.
• Autonomous agent build branch - Reference mini-app build instructions written for autonomous agents.

Research, Simulation & Reputation

• PyCircleSim - Agent-based simulator for Circles network dynamics in Python.
• pyfinder-dgen - Synthetic Circles data generator for pathfinder benchmarking.
• circles_arbbots - Arbitrage bots that help equilibrate prices across CRC tokens.
• Universal basic income on blockchain: the case of Circles UBI - Peer-reviewed analysis of Circles as a UBI mechanism (Frontiers in Blockchain).

Hackathon Projects

• BraceBuddy - NFC bracelet onboarding for Circles (ETHGlobal Brussels 2024, 1st prize).
• Woleth - Telegram-embedded EVM wallet using Circles invite mechanics (ETHGlobal Brussels 2024, runner-up).
• Famjam - Family currency that rewards kids for good behavior (ETHGlobal Brussels 2024, runner-up).
• Voting with UBI - DAO voting weighted by Circles group tokens (ETHGlobal Singapore 2024).
• Circles Subscriptz - Trustless recurring payments in CRC (ETHGlobal Prague 2025).
• Raila Circles - Trust-graph-based P2P uncollateralized lending with a Safe module and relayer margins (ETHGlobal Buenos Aires 2025, 1st place).
• Inner Circles - No-collateral CRC lending where 3+ community vouchers escrow trust; interest drops as vouchers grow (ETHGlobal Buenos Aires 2025, 2nd place).
• Past Hackathon Projects index - Maintained list with descriptions.

Background Reading

• Circles v2 Whitepaper - Canonical protocol whitepaper (PDF in repo).
• Glossary - Avatars, demurrage, hubs, mint policies, vaults, and more.
• Trust Score - How trust reputation is computed.
• Daily Burn / Demurrage - Why your balance shrinks 7%/year.
• Rule of Trust - How transitive trust enables strangers to pay each other.

Community

• Telegram - About Circles - Main builders + users chat.
• @aboutcircles on X - Announcements and ecosystem updates.
• GitHub - aboutcircles - All official repositories.
• Discord, Forum, and Farcaster: linked from the About Circles homepage (see top of this page).
• Email: hello@aboutcircles.com

Contribute

Contributions welcome - see contributing.md for the format and review criteria. Open a PR if your project, tool, or guide belongs on this list.