We introduce Circles, a new currency framework that leverages modern cryptography to build trust without centralized gatekeepers. By decentralizing money creation, Circles distributes the privilege of issuing currency to every individual, fostering a more inclusive and resilient monetary system.

Circles is built on a few powerful principles that make money creation fair, efficient, and resilient. By moving money creation from centralized institutions to individuals—and by harnessing real-life trust—Circles reimagines currency.

Build on the Circles Protocol

About Circles

Under the hood, Circles relies on five simple rules:

• Universal access allows anyone to open an account.

• Distributed issuance grants each account the right to mint 1 CRC per hour.

• Demurrage applies a 7 % yearly decay to every CRC, preventing early adopters from dominating the supply.

• A Rule of Trust lets users swap CRC 1:1 along their social trust graph, so individual non-fungible “personal monies” converge into a commonly spendable currency.

• Members of a Circles Groups can mint a shared CRC backed by members’ coins, giving communities their own monetary layer.

Circles also uses an invitation system for onboarding: existing users invite newcomers by paying 96 CRC, while the invitee receives 48 CRC as a welcome bonus. This helps protect network integrity and creates a meaningful cost to discourage spam accounts and Sybil style abuse.

Because payments flow along real-world social links, Circles is both resilient and versatile. Trust can be revoked at any time, shielding honest users from malicious actors, yet the transitive nature of swaps means you can still pay strangers seamlessly. Groups and Organizations add a “fast lane” for adoption: they pool liquidity, act as local or thematic currencies, and let communities balance efficiency against security. The result is a self-governing monetary network in which issuance, security and economic coordination rest with the people who use it.

This documentation helps developers explore Circles’ capabilities and delve into the Circles SDK and its various components.

When you become part of the Circles network, every person has their own personal Circles token and receives one Circle (CRC) per hour, unconditionally.

The trust network forms a social graph where each trust relationship acts as a link, allowing tokens to flow between individuals through these connections. This ensures that the value of Circles is supported by genuine social relationships, fostering a community-driven economy.

At the same time, this mechanism is an effective soft sybil protection, as it decentralises the verification process and relies on human judgment for trust, preventing fake accounts from compromising the network. Since the connections between Circles accounts have a limited capacity (defined by their balances of fungible tokens), this limits the impact of fake accounts that manage to get trusted by a credible member of the network to their direct surroundings.

In addition to individual CRC currencies, Circles has introduced the concept of Group Avatars and Currencies. The idea behind Group currencies is to aggregate social-economic value amongst groups, without the geographical bounds of where groups are generated or created. Group avatar tokens can't be minted based on time, rather they depend on collateral deposits from trusted tokens.

Group participation operates through Circles' trust network rather than formal membership. To receive and accept group tokens, you need to trust the group address, which allows you to hold and transact with their tokens. The group, in turn, must trust the types of tokens it will accept as collateral for minting.

Group token minting is a permissionless process open to anyone holding tokens that the group trusts. When you want to mint group tokens, you deposit your trusted tokens (which can be personal CRC, other group tokens, or any Circles tokens) as collateral through the groupMint() function. The group mints new group tokens proportional to the collateral deposited, while your collateral tokens are held in the group's treasury.

This is not a direct swap but rather a collateralization mechanism - your original tokens remain in the group's treasury and can be redeemed later by burning group tokens through the groupRedeem() function. The current system allows minting based on any quantity of trusted Circles tokens you hold, not limited to personal CRC tokens.

The trust relationships work bidirectionally: you trust the group to accept their tokens, and the group trusts specific token types to accept them as collateral. This creates a flexible, decentralized system where group currencies can be backed by diverse collateral from across the Circles ecosystem, enabling economic coordination without geographic or membership constraints.

Circles allows you to join the network as a human with a token ERC 1155 standard. You would have a profile and would require to be invited to join the network and start minting personal CRC token

Inviting a human to Circles

// Inviter side: send invite (escrows 100 CRC + trusts the invitee)
const inviter = await sdk.getAvatar('0xInviterAvatar'); // HumanAvatar
await inviter.invite.send('0xInviteeEOAAddress');

• Now, your invitee can accept the invitation / register by:

//Invitee side: accept Invitation
const inviteeAvatar = await inviteeSdk.register.asHuman('0xInviterAddress', {
  name: 'Alice',
  description: 'New Circles member',
});

// (Optional) If multiple inviters, redeem a specific one
await inviteeAvatar.invite.redeem('0xSpecificInviter');

Get an existing avatar

If you have the address of an existing avatar, you can get the avatar details by:

Human avatars accrue issuance continuously (capped at roughly 24 CRC per day) and expose helpers under avatar.personalToken:

const mintable = await avatar.personalToken.getMintableAmount();
console.log(`Mintable CRC: ${mintable.amount}`);

if (mintable.amount > 0n) {
  const receipt = await avatar.personalToken.mint();
  console.log('Mint transaction hash:', receipt.hash);
}

• getMintableAmount() returns the currently claimable amount plus the accrual window.

• mint() calls hubV2.personalMint() via the configured runner.

Get a profile for the avatar

This function fetches the current profile associated with the avatar. If no profile exists, it will return undefined.

const profile = await inviteeAvatar.profile.get();
if (profile) {
  console.log(profile.name, profile.description);
}

Update profile of the avatar

This function pins JSON to the Profiles service and updates the metadata digest on-chain. Returns the new CID.

If you already have your CID, you can use the function below to update the on-chain pointer:

const cid = 'QmYourIPFSCIDHere';

try {
  const receipt = await inviteeAvatar.profile.updateMetadata(cid);
  console.log('Metadata updated, tx:', receipt.hash);
} catch (err) {
  console.error('Error updating metadata:', err);
}

Trust determines which avatars will accept Circles issued by others. Circles SDK exposes avatar.trust helpers that batch safely (via Safe runner) or send single transactions (via EOA runners) while keeping expiry handling consistent and default under the hood.

Add Trust

• Trusting an avatar means you are willing to accept Circles they issue, transfers from them or along paths that rely on them are allowed while the trust is active.

• Passing an array batches all trust updates into one Safe transaction. EOA runners only support single addresses per call.

Remove Trust

Check Trust Direction

Inspect All Trust Relations

getAll() returns aggregated links where relation is one of:

• trusts – avatars you trust.

• trustedBy – avatars that trust you.

• mutuallyTrusts – avatars where trust is bidirectional.

You can use the avatar.balances helpers to read Circles balances with automatic v1/v2 handling. These methods rely on RPC only and work as soon as the SDK instance is initialized with a runner.

Get Total Balance

const totalBalance = await avatar.balances.getTotal();
console.log(`Total Circles balance: ${totalBalance.toString()}`);

• Automatically checks the correct hub version based on avatar.avatarInfo.

• Returns the sum of all Circles holdings (unwrapped + wrapped) for the avatar address.

Get Token Balances

• Returns an array of TokenBalanceRow entries for every token relevant to the avatar in the current context.

Base groups “invite” members by trusting their personal avatars; members must also trust the group avatar to mint group tokens as collateral.

Invite a Member (Trust Them)

• Trusting a member signals that the group will accept their personal token as collateral.

• Safe runners can batch invites: groupAvatar.trust.add(['0xA', '0xB']);.

Member Accepts (Trust the Group)

• Members must trust the group avatar before they can mint group tokens.

Revoke a Member (Untrust Them)

• Batching works the same way: groupAvatar.trust.remove(['0xA', '0xB']);.

Use balances.getTotalSupply() on avatars that expose a minted token (currently Base Groups).

Get Total Supply for a Base Group

import { Sdk, BaseGroupAvatar } from '@aboutcircles/sdk';

const sdk = new Sdk({ rpcUrl: 'https://rpc.aboutcircles.com' }, runner);
const avatar = await sdk.getAvatar('0xGroupAddress');

if (avatar instanceof BaseGroupAvatar) {
  const totalSupply = await avatar.balances.getTotalSupply();
  console.log('Total group token supply:', totalSupply.toString());
} else {
  console.log('Total supply is only available for BaseGroup avatars.');
}

• Returns the ERC‑1155 total supply for the group’s token ID.

In the Circles SDK, an Organization Avatar represents a non-human entity within the ecosystem. Unlike human or group avatars, it has distinct capabilities:

• Cannot mint tokens

• Can participate in the trust network

• Supports profiles for organization

Unlike group avatars, organizations don't have membership conditions. Organizations are designed to represent entities that participate in the Circles economy without issuing their own currency.

Organizations join Circles without invitations and don’t mint personal tokens.

Register the Organization

import { Sdk } from '@aboutcircles/sdk';

const sdk = new Sdk({ rpcUrl: 'https://rpc.aboutcircles.com' }, runner);

const orgAvatar = await sdk.register.asOrganization({
  name: 'My Organization',
  description: 'Circles-enabled community treasury',
  avatarUrl: '',         // optional
  previewImageUrl: '',   // optional
});

console.log('Organization avatar:', orgAvatar.address);

• The SDK pins the profile to the Profiles service, converts the CID to a metadata digest, and calls hubV2.registerOrganization.

• The returned OrganisationAvatar is ready for balances, transfers, trust, wrapping, group participation, etc.

Using an Existing Profile CID

The SDK fetches the profile to validate the name field before registering.

Organizations use the same trust surface as humans. Trust determines which avatars’ Circles they accept and who can route transfers through them.

Trust Another Avatar

• Default expiry is max uint96 (indefinite). Optionally pass an expiry timestamp (seconds since epoch).

• Safe runners can batch: orgAvatar.trust.add(['0xA', '0xB'], expiry).

Remove Trust

Inspect Trust Direction

List All Trust Relations

• relation is trusts, trustedBy, or mutuallyTrusts. Use this to identify who the org accepts and who accepts the org for routing and payments.

Here is an example code on how you can setup Circles SDK with a front-end framework like React.

  import React, { createContext, useCallback, useEffect, useState } from 'react';
  import { Sdk } from '@aboutcircles/sdk';
  import { circlesConfig } from '@aboutcircles/sdk-core';
  import { SafeBrowserRunner } from '@aboutcircles/sdk-runner';
  import { createPublicClient, http } from 'viem';
  import { gnosis } from 'viem/chains';

  export const CirclesSDKContext = createContext(null);

  export const CirclesSDKProvider = ({ children, safeAddress }) => {
    const [sdk, setSdk] = useState(null);
    const [runner, setRunner] = useState(null);
    const [address, setAddress] = useState(null);
    const [isConnected, setIsConnected] = useState(false);

    const initSdk = useCallback(async () => {
      try {
        if (!window.ethereum || !safeAddress) {
          // Read-only SDK without runner
          setSdk(new Sdk(circlesConfig[100]));
          setIsConnected(true);
          return;
        }

        const publicClient = createPublicClient({
          chain: gnosis,
          transport: http(circlesConfig[100].circlesRpcUrl),
        });

        const safeRunner = new SafeBrowserRunner(publicClient, window.ethereum, safeAddress);
        await safeRunner.init();

        setRunner(safeRunner);
        setAddress(safeAddress);

        const sdkInstance = new Sdk(circlesConfig[100], safeRunner);
        setSdk(sdkInstance);
        setIsConnected(true);
      } catch (err) {
        console.error('Error initializing Circles SDK', err);
        setIsConnected(false);
      }
    }, [safeAddress]);

    useEffect(() => {
      initSdk();
    }, [initSdk]);

    return (
      <CirclesSDKContext.Provider
        value={{ sdk, runner, address, isConnected, initSdk }}
      >
        {children}
      </CirclesSDKContext.Provider>
    );
  };

Circles is all about creating a fairer money system. Our current monetary system and most cryptocurrencies tend to benefit those with established wealth and market positions, making it challenging for newcomers to catch up. Wealth grows disproportionately for those already in the market, as time in the market often beats time to market.

Circles aims to solve this by ensuring equal opportunity for all. Each user continuously generates tokens at a rate of one Circle (CRC) per hour, regardless of when they join. Additionally, existing Circles incur a demurrage fee of 7% per year. By tying the issuance of tokens to time, a resource everyone has, Circles promotes fairness by giving everyone a chance to accumulate tokens and encouraging the active circulation of currency.

Issuance

Circles employs a unique token issuance mechanism where each user generates their own currency (CRC) at a steady rate of one token per hour. The minting rules are encoded in the so-called Hub, a token factory from which all individual Circles tokens are created.

Demurrage

All tokens are automatically demurred at a rate of 7% per year.

For human users, the demurrage is offset by the steady income of new CRC. Only after minting for 80 years (roughly a human lifespan) or through economic activity can a person become negatively affected by demurrage. Once the person dies, no new tokens are minted and all of the person's tokens are subjected to demurrage.

The following graph visualizes the balance of an account over time, assuming no economic activity and continuous minting of all CRC.

If understood as a tax, then the tax would be negative at first (you get money), but once your balance reaches the threshold of 125.000 Circles, it turns positive (you loose money).

Circles v2 is built on the ERC1155 token standard. Here, the Hub uses a standard allowance to facilitate path transfers. The token metadata mimics as profile.

In Circles v2, there is a limit that allows a maximum minting amount of 14 days' worth of Circles. Minting can be stopped manually if required.

Circles is a decentralized protocol with a social and economic value for humans, communities and groups. Circles is not a crypto startup or product in general, but a collective effort to bring a fair distribution model for the money created, owned and shared by people.

Explore our developer documentation, and join us in our mission to create a fair and sustainable economy for all.

Circles V2 Core Components

Our developer documentation portal provides comprehensive guide to build using Circles SDK, SDK references, contract addresses, and code examples to help you integrate Circles into your applications and build upon our ecosystem.

If you want to develop a server or client application that utilizes Circles, and allow you to utilize trust connection and personal/group currencies, then Circles SDK would be your entry point. Based on your need, you can pick to develop any avatar post initialization of SDK.

The is a TypeScript library that allows you to integrate Circles protocol into your dApp to implement avatars, profiles, token transfers and build trust connections for your use-case. Under the hood, Circles SDK utilizes deployed hub contracts on Gnosis Chain, pathfinder for finding trust network paths and profile service and Circles RPC.

To use the Circles sdk, install the primary npm package

Features:

• Instantiate Sdk once and work with human, organization, or group avatars through a unified interface.

The SDK is built around the concept of avatars. An avatar is a Circles user and is used to interact with other Avatars.

• New Circles users must sign up.

• For existing Circles users, you can simply get exisiting avatars by address.

Creating a new avatar

You can use avatar.transfer utilities to reason about and send Circles with or without pathfinding.

Pathfinder-based max flow from your avatar to a recipient:

• Computes the largest flow permitted by your trust graph and current balances.

• Selects routes through trusted avatars and wrapped tokens automatically.

Group avatars are a type of avatar in the Circles ecosystem that represent collective entities rather than individual users.

Group Structure

Each group in Circles has:

• A unique blockchain address (similar to individual avatars)

• A specific type identifier

• An owner who has administrative control

• A treasury where tokens are stored

• A mint policy that governs token creation

• A name and symbol for its tokens

• A membership system

• Groups also maintain a count of their members and can store metadata via IPFS CIDs (Content Identifiers).

• Minting: Groups can mint their own tokens using collateral from members

• Redemption: Members can redeem group tokens for the underlying collateral

Groups within the Circles ecosystem serve several important purposes:

1. Enabling Collective Economic Action: Groups allow multiple individuals to create shared economic entities with their own currencies, extending Circles beyond personal tokens.

2. Creating Community Currencies: Groups can mint their own tokens backed by collateral, allowing communities to create currencies tailored to their specific needs.

3. Pooling Resources: The group treasury system allows pooling of resources from members.

• They can set membership conditions to define who can be part of the group

• They can register short names with a nonce

• They can trust avatars individually or in batches with condition checks.

sdk.register.asGroup

Mint Base Group tokens by sending collateral through the trust graph to the group’s mint handler. The groupToken helpers on HumanAvatar and OrganisationAvatar handle pathfinding and wrapped balances automatically.

• Uses the pathfinder to route collateral (including wrapped tokens) to the group’s mint handler.

• It will fail if trust or liquidity is insufficient to deliver the requested amount.

You can use the RPC helpers on sdk.rpc.group to search for Base Groups and to fetch memberships for an avatar. These methods work with cursor-based pagination via PagedQuery.

Initialize RPC Access

import { Sdk } from '@aboutcircles/sdk';
import { CirclesRpc } from '@aboutcircles/sdk-rpc';

// Preferred: reuse the RPC client from an SDK instance
const sdk = new Sdk({ rpcUrl: 'https://rpc.aboutcircles.com' });
const rpc = sdk.rpc;

Find Groups

Fetch groups with an optional filter and limit:

const groups = await rpc.group.findGroups(10, {
  nameStartsWith: 'Community', // optional filters
  // ownerIn: ['0xOwner...'],
  // typeIn: ['BaseGroup'],
});

console.log('Retrieved groups:', groups);

• findGroups(limit, params?) pulls pages under the hood and returns up to limit rows.

Get Group Memberships for an Avatar

getGroupMemberships returns a PagedQuery; call queryNextPage() to iterate.

You can continue paging while currentPage?.hasMore is true.

Retrieve user profile data using the Profiles Nethermind plugin. You can:

• Create new user profiles

• Search existing profiles using parameters such as:

  • Name

Circles Tools is a collection of useful tooling for the community. These tools can be used as an extension to the circles core app for niche, specific and advanced usecases.

Here is a detailed list of tools, you can currently use:

• Group Checker

  This tool displays detailed information about Circles group memberships and token balances. It can fetch on-chain data like ERC20 supplies, fees, and balances using a smart contract and direct links to relevant explorers and swap platforms.

• Group Creator

  This tool allows users to create Circles groups with customizable metadata and membership conditions. It supports input of service address, group name, symbol, and optional initial trust conditions for setup.

• Group Manager

  This tool enables group owners to manage and update their Circles group contracts directly from the browser. Owners can view contract details, add or remove trusted members, and modify settings like service or fee collection addresses.

• Profile Checker

  This tool provides a detailed overview of any address’s Circles v1 and v2 profile details like profile data, token balances, trusted relationships, and live ERC20 prices, including bot classification and expiry info.

• Safe State & Tx Hash Checker

  This tool allows users to inspect the state of a Gnosis Safe (owners, threshold, nonce) and compute a Safe transaction hash with full control over parameters like gas settings, operation type, and calldata. It also includes an interactive function encoder to help generate calldata from ABI inputs, and shows the full execTransaction calldata when approvals meet the threshold.

• Trust Graph Visualizer

  This tool visualizes the web of trust relationships in the Circles ecosystem using an interactive force-directed graph. It supports avatars, PageRank-based trust scores, dynamic expansion (recursive and top-ranked), and rich filtering (Humans, Groups, Orgs). Users can explore any address, see stats and trust rankings in a sortable table, and view incoming/outgoing trust via tooltips and double-click expansion.

• Trust Path Visualizer

  This advanced visualization tool helps users explore trust flow paths between two Circles addresses using an interactive Sankey diagram.

  It calculates on-chain trust paths for a given Circles token transfer amount, retrieves real-time token supply capacities, and visualizes flow bottlenecks. It’s ideal for understanding how CRC tokens route across trust relationships and for debugging why a transfer may or may not succeed.

• Personal CRC Replenisher

  This tool lets Circles users replenish their own CRC token balance by routing it through the trust network back to themselves.

  It calculates the maximum amount you can send to yourself using existing trust paths, and builds a transaction to call operateFlowMatrix on the Circles Hub.

• Circles Backing dApp

  This tool allows users to back their Circles tokens (CRC) with real-world assets like WBTC, WETH, GNO, or sDAI through a Safe-based flow on Gnosis Chain. It supports both Safe Apps and MetaMask wallet connections, computes a deterministic CirclesBacking contract address for any given Safe, registers appData with CowSwap to enable post-swap hooks, and guides the user through submitting two required transactions: approve() USDC.e to the factory and safeTransferFrom() CRC tokens via Hub V2.

• LBP Starter

  This tool helps users easily create and manage Liquidity Bootstrapping Pools (LBPs) using their Circles tokens. It allows local groups or organizations to launch an LBP by selecting a group token (CRC), choosing a paired asset (like sDAI or GNO), specifying the amount of each token, and optionally configuring advanced parameters such as weight curves, swap fees, and duration. It also supports reloading or continuing with existing LBP contracts for inspection or finalization.

• Token Distribution Checker

  This is an analytics tool for exploring the distribution of ERC-1155 Circles tokens. It allows users to input any Circles-compatible token address and fetch a full breakdown of its holders using the Circles Hub RPC API. The tool visually presents token holdings using a pie chart (with custom legends), paginated data tables, and balance percentages per holder. Each address is enriched with profile names (if available), explorer links, quick copy buttons, and the ability to recursively check other token distributions. Users can export the full dataset as CSV, verify the raw API data via a debug panel, and dynamically navigate token ownership. This tool is ideal for community organizers, protocol designers, or auditors who want transparency and insight into token spread, supply concentration, and holder identity.

• Legagacy Circles Safe Creator

  This tool is designed to help users deploy a Gnosis Safe (v1.1.1) contract instance with a single owner, tailored for legacy use within the Circles ecosystem. By connecting a MetaMask wallet, users can specify any valid Ethereum address as the owner and generate a new Safe contract using a proxy factory and master copy on Gnosis Chain. The tool handles address validation, transaction submission, and post-deployment verification to confirm that the specified address was correctly set as the owner of the Safe. It is especially useful for onboarding Circles users who need a compatible Safe to manage CRC tokens and interact with legacy dApps.

• Onboarding Helper

  This tool allows people to easily join a Circles group by scanner a QR code.

• Equilibrium Analaysis

  This tool provides a dynamic view into market efficiency and arbitrage activity within the Circles economy. It visualizes the moving average of arbitrage profit opportunities over time—expressed in USD—based on configurable time windows, helping identify trends in CRC market imbalances. Simultaneously, it offers a price equilibration analysis by showing the distribution of price spreads between liquid CRC token pairs, flagging deviations from parity using customizable thresholds, liquidity filters, and deviation types (absolute or relative). Together, these insights help traders, analysts, and protocol maintainers detect inefficiencies, monitor arbitrage potential, and assess the overall health of price discovery in the Circles ecosystem.

• Pathfinder App

  This is an advanced visualization and simulation tool that computes and displays optimal token transfer paths through the Circles network graph. Users can specify a source address, destination address, and CRC value, along with custom token inclusion filters for both sender and receiver. The tool supports optional wrapped token inclusion and lets users configure visual and performance parameters—such as edge curvature, capacity gradients, node/edge labels, and tooltip details—for clarity and analysis. Upon clicking “Find Path,” the graph engine simulates feasible routes, showing flow capacity and rendering performance in real-time. This makes the Pathfinder useful for debugging trust routes, analyzing payment viability, and exploring how CRC tokens can move through the social trust graph, especially in complex multi-hop scenarios.

Purpose limitation: The Trust Score is provided only for Circles-related trust, anti-abuse, spam and Sybil-resistance use cases (for example, filtering obvious Sybil accounts, protecting community airdrops, or shaping access to Circles-native groups and offers in a proportional way). You must not use it to make or automate unrelated, high-impact decisions about individuals – for example, decisions about employment, housing, off-chain financial products or credit, insurance, access to public services, or other real-world eligibility and access decisions.

Here are some of the past hackathon projects built with Circles. You can use these as a reference or to get inspiration of what kind of applications to build.

1. EthGlobal Brussels 2024

BraceBuddy allows to onboard easily and in a fun way people to the Circles ecosystem with NFC!

Woleth is an easy to use EVM wallet embed into Telegram designed to build a Social Graph utilizing Circle's invite mechanism.

Famjam is a dapp that uses Circles to create a family currency to incentivize kids for good behaviour.

2. EthGlobal Singapore 2024

Voting with UBI is a dapp which implements a voting mechanism for DAOs by utilizing Circles group tokens.

3. EthGlobal Prague 2025

Circles Subscriptz allows users to securely, trustlessly & smoothly authorize recurring payments.

Circles tokens (CRC) are primarily ERC‑1155 balances, but most DeFi tooling expects ERC‑20s. Wrapping converts CRC into ERC‑20 wrappers so you can reach AMMs, lending markets, or bridges while keeping Circles' properties.

Why wrap?

• AMMs and routers typically accept only ERC‑20 tokens.

• Lending/borrowing markets need ERC‑20 collateral and debt assets.

• Bridges and cross‑chain tools usually whitelist ERC‑20s.

• Demurraged (decaying): Keeps Circles' time‑based decay. Wrapped balances shrink as demurrage accrues. Use when external protocols should still respect Circles' economics.

• Inflationary/static: Balance stays fixed for ERC‑20 compatibility. Use for AMM liquidity, lending collateral, or bridging where decay would break integrations.

Transactions require a configured runner (EOA or Safe) with the SDK.

Deploys (or reuses) a demurraged ERC‑20 wrapper for the avatar’s CRC and transfers the specified amount into it.

Creates or fetches a static ERC‑20 wrapper so balances never decay while wrapped.

Pass the ERC‑20 wrapper contract address you received (via the helper above or your own tracking).

Demurrage continues while wrapped; the redeemable amount may be lower than what was deposited.

Balances are static while wrapped; unwrapping returns the same amount of CRC.

• Pick demurraged wrappers to preserve Circles' economic incentives in external protocols; pick static wrappers for maximal ERC‑20 compatibility.

• You can wrap any ERC‑1155 Circles token you hold—not just your personal token—by passing its avatar address to asDemurraged or asInflationary.

• Store or fetch wrapper addresses for DeFi integrations; use

Subscribe

To subscribe, you need an initialized CirclesData class.

const circlesRpc = new CirclesRpc("

const circlesRpc = new CirclesRpc("

Then call the subscribeToEvents() method and supply the address of the avatar to subscribe to:

const avatarEvents = await data.subscribeToEvents("0x...");
avatarEvents.subscribe(event => {
    console.log(event);
});

If you want to subscribe to all events, call it without parameter:

const avatarEvents = await data.subscribeToEvents("0x...");
avatarEvents.subscribe(event => {
    console.log(event);
});

Query past events

If your client missed some events, you can query all events for a specific avatar in a block range.

const avatarEvents = await data.getEvents("0x..", 9000000, 10000000);

You can omit the last parameter (toBlock) to query from fromBlock to the latest block:

The above methods yield CirclesEvents. All events have at least the following base properties:

• $event: CirclesEventType One of the event types listed below

• blockNumber: number In which block the event occurred

• timestamp?: number When the event occurred

Here's a list of all event types. Please refer to the for the event properties.

Circles SDK exposes human avatars through the HumanAvatar class, which implements the AvatarInterfaceV2 contract. Each instance wraps the Circles V2 hub contracts, profile service, and pathfinding helpers so apps can manage invitations, minting, trust, and transfers with minimal boilerplate.

• Invitation-based onboarding – every human avatar must be invited by an existing avatar that escrows 100 CRC via avatar.invite.send.

This starter kit showcases a simple method for Circles transaction based data transfer: execute a transfer via Gnosis, then verify on-chain intent by polling Circles events for CrcV2_TransferData and matching recipient + data.

The core idea is simple:

• Treat transfer data as an application-level idempotency key.

Circles pathfinder calculates “how much and through which tokens can flow from A to B” based on trust and balances (wrapped and unwrapped). You can use it to:

• Preview a route and achievable amount.

• Feed TransferBuilder or custom operateFlowMatrix calls.

Entry points

• High-level SDK: const rpc = (sdk as any).rpc; rpc.pathfinder.findPath / findMaxFlow

• Standalone: const rpc = new CirclesRpc(config.circlesRpcUrl);

• findPath(params: FindPathParams): Promise<PathfindingResult>

• findMaxFlow(params: Omit<FindPathParams, 'targetFlow'>): Promise<bigint>

• from (Address, required): Source avatar.

• to (Address, required): Destination avatar.

• targetFlow (bigint, required for findPath

Computes a path for a requested amount; returns what is actually achievable plus hop-by-hop legs.

PathfindingResult:

• maxFlow – achievable flow for this request.

• transfers – ordered legs; tokenOwner is the ERC1155 owner or wrapper used in that hop.

If maxFlow < targetFlow, decide to scale down or show an error.

Returns the absolute maximum possible flow between two avatars with the same options.

Use for sliders, validation, or deciding if you must unwrap/wrap first.

• Wrapped tokens: useWrappedBalances: true enables consuming inflationary/demurraged ERC20 wrappers the sender holds.

• Token pinning/bans: Use fromTokens/toTokens to force specific personal or group tokens; use the exclude* variants to forbid costly or undesired wrappers.

• Easiest: call TransferBuilder.constructAdvancedTransfer(from, to, amount, options)—it runs findPath, adds unwrap/rewrap, approvals, and returns an ordered tx array.

• Manual: convert PathfindingResult to operateFlowMatrix:

• createFlowMatrix(from, to, maxFlow, transfers) – turns a PathfindingResult into flowVertices, flowEdges, streams, packedCoordinates for hubV2.operateFlowMatrix.

• maxFlow === 0: check mutual trust or unwrap static/demurraged balances back to ERC1155.

• Paths needing wrapped balances will fail unless useWrappedBalances is true.

The previously shown CirclesData class returns CirclesQuery<T> objects for all paged query results. You can execute custom queries against all tables in the Circles index and filter with them.

Write a query

First you'll need to define a query. The basic structure of a query is the same as for a basic SQL select. It has the following fields:

• namespace: Used to distinguish between tables and views as well and to tell the tables of the two Circles version apart from each other.

• table: The name of the table you want to query.

• columns: A list of column names you want to select.

• filter: A list of filter conditions that must be met.

• sortOrder: Can be 'asc' or 'desc'.

• limit: How many rows to return (max: 1000).

Here is a query that reads all avatars with type group. Other avatar types you can try are human and organization.

You can define a type for the rows of your query, or just go with any if the type doesn't matter.

If you want to specify a custom type, it must extend the EventRow type. The EventRow type contains the blockNumber, transactionIndex and logIndex fields which are required for pagination.

To execute the query definition, you'll need a CirclesRpc instance. Create one and pass the Circles rpc url to the constructor.

Then create a CirclesQuery<MyGroupType> instance.

Call getNextPage() to retrieve the first page of the result set. You can then access the results through the currentPage property. This property includes the results themselves, along with firstCursor, lastCursor, limit, size, and sortOrder.

You can extend the CirclesQuery with computed columns. Computed columns are defined by a callback that takes in the row and returns a new value. Here we convert the value of the previously queried cidV0Digest field (which is originally a hex-string) to a CID in Qm.. format.

The new column should be added to the custom type.

Then you can execute the query just like you did before. The calculated column function will be executed for each row in a page.

ERC-1155 is an Ethereum token standard that enables the efficient transfer and bundling of multiple fungible and non-fungible tokens in a single transaction. This multi-token standard allows for the creation of complex token systems, such as those used in gaming or supply chain management, where different types of tokens need to be managed simultaneously.

The standard introduces a new set of functions, including safeTransferFrom, safeBatchTransferFrom, and balanceOfBatch, which allow for the transfer and querying of multiple token balances in a single call. This reduces gas costs and simplifies token management compared to using multiple ERC-20 or ERC-721 contracts.

ERC-1155 tokens are identified by a unique combination of an address and an ID, allowing for the creation of an unlimited number of token types within a single contract. The standard also includes an optional metadata extension, enabling developers to associate additional information, such as images or descriptions, with each token type.

Initialization

Most of the previously shown avatar methods internally use the CirclesData class with filters for the current avatar address. If you already have a configured Sdk instance, you can use the sdk.data property to access the class:

const data = sdk.data;

Otherwise you can also create an instance like this:

const circlesRpc = new CirclesRpc("https://rpc.aboutcircles.com/");
const data = new CirclesData(circlesRpc);

Get avatar info

The getAvatarInfo(avatar: string): Promise<AvatarRow | undefined> method finds basic information about an avatar. This includes the signup timestamp, circles version, avatar type (human, organization or group), and token address/id as well as it's profile CID (if any).

const avatarInfo = await data.getAvatarInfo("0x...");
if (avatarInfo) {
   console.log("Avatar is signed up at Circles");
} else {
   console.log("Avatar is not signed up at Circles");
}

Get token info

The getTokenInfo(tokenId: string): Promise<TokenInfoRow | undefined> methods finds basic information about a Circles token. This includes the creation timestamp, circles version, token type (human or group) and the address of the avatar that created the token.

The total Circles balance of an avatar is the sum of all it's personalized and group token holdings. It can be queried with the getTotalBalance(avatar:string): Promise<string> method. There is a separate method for each Circles version.

In contrast to the above method, the getTokenBalances(avatar: string): Promise<TokenBalanceRow[]> method gives a detailed overview of an avatar's Circles holdings. As with the method above, this one also exists for both versions of the Circles protocol.

The result row contains the token, balance and the tokenOwner.

The getTransactionHistory(avatar: string, pageSize: number): CirclesQuery<TransactionHistoryRow> method can be used to query all incoming and outgoing Circles transfers from and to an avatar. This includes minting and transfers of personal and group Circles for v1 and v2.

The result rows have the following properties:

• timestamp When the transaction happened

• transactionHash

• version If the transaction happened in Circles v1 or v2

The results are ordered in descending order.

The getTrustRelations(avatar: string, pageSize: number): CirclesQuery<TrustListRow> method can be used to query the effective trust events for an avatar. Already expired or removed trust relations are omitted from the results.

In contrast to the above method, this method queries all relevant trust events and groups mutual trust events into a single row instead of one for each direction.

The result rows have the following properties:

• subjectAvatar The acting avatar

• relation The relation between the acting avatar and the one it's related to

• objectAvatar The other avatar

The possible relations are: trusts, trustedBy, mutuallyTrusts, and selfTrusts. The last one (selfTrusts) exists because, in Circles, every avatar trusts itself.

Circles groups have a name and symbol that's stored on-chain. You can use the findGroups(pageSize: number, params: GroupQueryParams): CirclesQuery<GroupRow> method to find groups by name or symbol.

The params parameter can be used to filter and order the result set by the name and symbol of a group.

Use the method as following:

You can query the group memberships of an avatar using the getGroupMemberships(avatar: string, pageSize: number): CirclesQuery<GroupMembershipRow> method to get a list of all groups an avatar is a member of.

The result rows contain the following properties: group, member, expiryTime.

Avatars can invite others to join Circles. The getInvitations(avatar: string, pageSize: number): CirclesQuery<InvitationRow> method returns a list of invitations sent by the specified avatar.

Th e result rows contain the follwing properties: timestamp, transactionHash, inviter, invited.

You can query who invited an other avatar by calling getInvitedBy(avatar:string): Promise<string|undefined>. If the avatar wasn't invited, the method returns undefined.

Sdk class

Constructor: new Sdk(config?: CirclesConfig, contractRunner?: ContractRunner)

• config defaults to circlesConfig[100] (Gnosis)

• contractRunner required for any state-changing call (see ContractRunner below)

Top-level properties:

• core: low-level contract wrappers (@aboutcircles/sdk-core)

• rpc: RPC client (@aboutcircles/sdk-rpc)

• getAvatar(address) → HumanAvatar | OrganisationAvatar | BaseGroupAvatar

Registration (sdk.register.*)

• asHuman(inviter, profile) → HumanAvatar

• asOrganization(profile) → OrganisationAvatar

Profiles (sdk.profiles.*)

• create(profile) → cid

• get(cid) → Profile | undefined

Tokens (sdk.tokens.*)

• getInflationaryWrapper(address) → wrapper address or zero

• getDemurragedWrapper(address) → wrapper address or zero

• getHolders(tokenAddress, limit?, sortOrder?) → PagedQuery<TokenHolderRow>

Groups (sdk.groups.*)

• getType(avatar) → group type (currently unsupported)

• getMembers(groupAddress, limit?, sortOrder?) → PagedQuery<GroupMemberRow>

• getCollateral(groupAddress)

Read-only convenience interface:

• getAvatar(address) → AvatarInfo | undefined

• getTrustRelations(address) → AggregatedTrustRelation[]

Minimal contract runner the SDK expects when sending transactions:

• address (sender)

• publicClient (viem client for reads)

• init(): Promise<void>

Obtained via sdk.getAvatar(address). All mutate calls require a runner.

• getTotal() → total CRC

• getTokenBalances() → TokenBalanceRow[]

• getTotalSupply()

• add(avatar | avatar[], expiry?)

• remove(avatar | avatar[])

• isTrusting(address) / isTrustedBy(address)

• get() → Profile | undefined

• update(profile) → cid

• updateMetadata(cid)

• getTransactions(limit?, sortOrder?) → PagedQuery<TransactionRow>

• direct(to, amount, tokenAddress?, txData?) → tx receipt

• advanced(to, amount, options?) → tx receipt (pathfinding + unwrap/rewrap)

• getMaxAmount(to) / getMaxAmountAdvanced(to, options?)

• asDemurraged(avatarAddress, amount) → tx receipt

• asInflationary(avatarAddress, amount) → tx receipt

• unwrapDemurraged(wrapperAddress, amount) → tx receipt

• subscribeToEvents() → sets avatar.events observable

• unsubscribeFromEvents()

• events

• getAvailableAmount() → mintable CRC

• mint() → tx receipt

• stop() → tx receipt (irreversible)

• mint(group, amount) → pathfound transfer to mint handler

• getMaxMintableAmount(group) → bigint

• redeem(group, amount)

Same groupToken surface as HumanAvatar; lacks personal minting.

• mint(group, amount)

• getMaxMintableAmount(group)

• redeem(group, amount)

• setProperties.memberRequirement(group, newRequirement)

• setProperties.baseName(group, name, symbol)

• Provide a ContractRunner for any write call; you can use SafeBrowserRunner/SafeContractRunner or your own viem-based runner.

• Pathfinding options for transfers mirror FindPathParams (useWrappedBalances, token include/exclude lists, maxTransfers, simulatedBalances

Circles avatars are ERC‑1155 tokens whose metadata field points to an IPFS CID. The JSON stored at that CID contains the human-friendly profile (name, description, images, etc.) that explorers and UIs render. @aboutcircles/sdk exposes helpers on every avatar instance, while @aboutcircles/sdk-profiles provides you a lightweight client for direct pin/get calls.

The profile payload mirrors the Profile interface from @aboutcircles/sdk-types, and the Circles profile service enforces the same shape when accepting uploads.

Gets an avatar instance by address.

• Parameters:

  • avatarAddress (required): Avatar wallet address.

This guide explains how to use the latest @aboutcircles packages to build a browser-ready Circles dApp. Follow the steps to move from wallet prerequisites to a fully initialised Sdk instance capable of handling avatar reads, trust writes, transfers, profile updates, and the auxiliary helper surfaces exposed in v2.

1. Prerequisites

• Browser wallet such as MetaMask or Rabby.

• Gnosis Chain (chain ID 100) configured inside the wallet. Double-check the RPC endpoint, currency symbol (xDAI), and block explorer entries via the .

• A small amount of xDAI for gas (available from the ).

Keep the wallet unlocked in the same browser context that will load your dApp so the runner can interact to window.ethereum.

Install whichever modules you plan to import directly. @aboutcircles/sdk already depends on the others, but pinning them in your app keeps the versions aligned across bundlers.

• @aboutcircles/sdk – high-level surface your UI consumes (avatars, registration, helper namespaces).

• @aboutcircles/sdk-core – typed contract wrappers plus circlesConfig.

• @aboutcircles/sdk-types

• Sdk is the primary entry point exposing avatar namespaces (balances, trust, transfer, profile, etc.).

• Core/circlesConfig

Need multisig support? @aboutcircles/sdk-runner exports SafeContractRunner (backend) and SafeBrowserRunner (front-end Safe Apps). Swap your custom runner with those when you integrate Safe-based flows.

This object already contains:

• Service URLs: circlesRpcUrl (aggregated Circles RPC), pathfinderUrl, and profileServiceUrl.

• Canonical contract addresses: v1HubAddress, v2HubAddress, nameRegistryAddress, invitationEscrowAddress

An EOA runner is ideal for MetaMask/Rabby-style single-signers. The snippet below shows a minimal implementation that satisfies the ContractRunner interface with the help of viem:

Key behaviors:

• init() requests wallet access and enforces the correct chain ID before any on-chain action.

• sendTransaction() loops through every TransactionRequest emitted by avatar helpers or TransferBuilder, ensuring multi-step flows (pathfinding, wrapped transfers, etc.) complete in order.

Prefer a Safe-based UX? Replace the custom runner with SafeBrowserRunner.create(rpcUrl, window.ethereum, safeAddress, gnosis) (or the server-side SafeContractRunner) from @aboutcircles/sdk-runner. Both satisfy the same interface.

When you need extra control—analytics dashboards, dry-run tooling, custom transfer flows—instantiate the underlying modules alongside the Sdk:

• Core returns raw transaction requests for HubV2, BaseGroups, Lift ERC-20 wrappers, etc.

• CirclesRpc streams balances, trust graphs, profile search results, and transaction history straight from the Circles indexers.

• TransferBuilder leverages @aboutcircles/sdk-pathfinder