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.

Together these rules guarantee fair access to new money while deterring Sybil attacks and other abuses.

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.

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.

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.

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.

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.

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.

Mint Group Tokens

const groupAddress = '0xGroupAddress';
const amount = BigInt(100); 

try {
  const receipt = await avatar.groupToken.mint(groupAddress, amount);
  console.log('Minting successful:', receipt.hash);
} catch (error) {
  console.error('Minting failed:', error);
}

• 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.

Check Maximum Mintable (Recommended)

This will compute the largest flow to the group’s mint handler with the current trust relations and balances.

Circles V2 Core Components

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.

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)

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.

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.

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.

The Circles SDK 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.

Circles SDK :

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.

• Fetch total and per-token Circles balances (demurraged and static) for any avatar.

• Add, remove, batch, and audit trust relationships across the network.

• Execute direct or advanced multi-hop transfers with automatic pathfinding and flow-matrix generation.

• Check mintable amounts, mint daily issuance, stop minting, and manage ERC20 wrapper states.

• Store, update, and resolve avatar profiles, metadata digests, and short names via the profile service.

• Register humans, organizations, and groups while handling invitation escrows end-to-end.

• Query trust graphs, avatar info, wrapper addresses, token holders, and group memberships from convenience namespaces.

• Deploy BaseGroups, configure services and membership conditions, and analyze holders or memberships.

• Compute liquidity paths, unwrap/re-wrap flows, and generate operateFlowMatrix payloads programmatically.

• Plug in EOA or Safe runners to batch transactions and execute all avatar writes with consistent error reporting.

Dependency packages

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).

Implementation

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.

Halting Mint

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.

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:

• 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.

Full Example

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

Get Maximum Transferable Amount

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

const maxTransferable = await avatar.transfer.getMaxAmount('0xRecipient');
console.log(`Maximum transferable amount: ${maxTransferable.toString()}`);

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

Transfer CRC with Pathfinding

• Selects routes through trusted avatars and wrapped tokens automatically.

• Maximum transferable may be lower than your raw balance if trust is missing or tokens are locked in wrappers; check getMaxAmount first.

Direct Token Transfer (Specific Token)

• Bypasses pathfinding; only works if you already hold the target token (personal ERC1155 or wrapped ERC20).

• Provide a token address to send wrapped balances or omit to use your personal token.

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:

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

Base Groups are capable of following:

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

• They can register short names with a nonce

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

• 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.

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).

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

Wrapper choices

• 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.

Wrapping via avatar.wrap

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

Demurraged ERC‑20

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

Inflationary/static ERC‑20

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

Unwrapping back to ERC‑1155

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

Demurraged unwrapping

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

Static wrapper unwrapping

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

Note:

• 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 sdk.core.liftERC20.erc20Circles(type, avatar) to look them up after deployment.

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.

Get Validated

After you have onboarded at least 10 members into your Circles Groups, please reach out to us via Telegram or Discord to get your group validated.

You can reach out Circles team via Telegram ord Discord #Groups channels.

When people join your group, you can support your group by trusting and transacting in CRC to create an ecosystem of reciprocal value, where Circles can become the social and economic glue for your group.

Once your group has been created, the next step is to integrate Circles into what your group already does. The goal is to find a use case that naturally connects your group’s mission or activity with the core features of Circles.

Propose a Use Case

Think about how Circles can enhance your community’s existing work. For example:

• Joining your group in Circles could signal alignment or participation in your project or initiative.

• Circles can allow your community to build a trust graph among members who already support each other in other contexts.

• Circles groups can help members coordinate, reward, or recognise contributions.

Brainstorm & Iterate with your group

We recommend gathering your core group and holding a brainstorming session:

• What do we value as a group?

• How can Circles help us circulate trust, care, or currency among ourselves?

• How might we invite others into this ecosystem meaningfully?

Example Use Cases

Here are some real-world examples of how communities are already using Circles Groups. These are just a starting point. Your group can create its own unique use case that fits your goals, values, or community needs. We encourage you to explore what’s possible and make it your own.

Helpful Resources

Thanks for your interest in contributing! Follow these quick steps to open a pull request. We would encourage both technical and non-technical contributions. Technical contributions may include improvisations and addition of new details for the Circles SDK while non-technical contributions can be creating detailed user oriented guides on various Circles features. All non-technical guides should be created under the User Guides folder.

Prerequisites

- Node.js (v18+ recommended)

- Git + GitHub account

- Markdown editor or IDE (e.g., VS Code)

Steps to Contribute

1. Fork & Clone

Fork the repo -

2. Create a New Branch

3. Install Dependencies & Start Dev Server

Preview: http://localhost:3000

4. Make Your Changes

• Edit or create .md files inside the docs/ folder.

• Follow the tone and structure of existing content.

5. Commit & Push

6. Open a Pull Request

• Visit your fork on GitHub.

• Click “Compare & pull request”.

• Base repo: aboutcircles/circles-docs, branch: main.

After that, your contribution will be reviewed shortly. Thank you for helping improve Circles documentation!

💡 Query Circles Profiles

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

• Create new user profiles

• Search existing profiles using parameters such as:

  • Name

  • CID (Content Identifier)

  • Description

  • Wallet Address

1. Create a Profile (POST request)

2. Get a Profile by CID (GET request)

3. Get Multiple Profiles by CIDs (GET request)

4. Search Profiles by Name (GET request)

5. Search Profiles by Description (GET request)

6. Search Profiles by Address (GET request)

7. Search Profiles by CID (GET request)

8. Search Profiles with Multiple Criteria (GET request)

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.

Protocol Level Group

The most basic group construct is defined in the Hub contract.

Every group has its own CRC–token. Groups have members (defined as accounts they trust). In theory, groups can also trust other groups.

Subscribe

To subscribe, you need an initialized CirclesData class.

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

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.

Circles SDK

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.

• What are Circles Groups?

• How To Create a Group?

• Technical Group Details

• What's Next?

What are Circles Groups?

Circles Groups allow communities to engage with a new fair currency protocol, earn rewards, and grow their networks meaningfully. Groups have the freedom to define their own rules, membership criteria, and internal economies. Each group can decide who qualifies to join, whether it's based on location, shared values, participation level, or existing trust relationships.

Circles groups help communities build trust, collaborate, and create shared economic value. Each group has its own currency, allowing members to exchange their personal CRC tokens for group tokens. This system enables real-world use cases and empowers communities by increasing the utility of CRC tokens through demand and adoption. In the future, demand for group tokens can grow as local donors and businesses begin to accept them.

Why Groups Matter

• Group currencies increase daily CRC usability

• They promote internal circulation and demand for CRC

• They power real-world use cases, all while staying connected to the broader Circles network

Key Takeaways

• You only need 3 people to start a group

• Group tokens are backed by the personal CRC of members

• Groups set their own fees for users, which are completely customizable

• The more your group uses and promotes its token, the more valuable it becomes.

Ready to build your community? In the next section, you'll find a clear, step-by-step guide to creating your Circles Group. We've broken down the process into easy-to-follow actions, ensuring you can set up your group quickly and efficiently.

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.

Define a row type

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.

Execute the query

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.

Add computed columns

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.

Sdk class

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

• config defaults to circlesConfig[100] (Gnosis)

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.

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

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.

Key Characteristics

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

• Profile-backed identities – v2 humans always reference an IPFS CID (pinned through the Profiles service) that stores metadata such as name, description, and media URLs.

• Personal token minting – humans accrue up to 24 CRC per day and can mint accumulated issuance via avatar.personalToken.mint.

• Trust graph participation – avatar.trust.add/remove/isTrusting manages bilateral trust needed for pathfinding and transfers.

• Transfer orchestration – avatar.transfer.direct and avatar.transfer.advanced support both direct CRC transfers and multi-hop, wrapped-balance flows.

AvatarRow Data

Human avatars retrieved from Sdk#getAvatar or CirclesRpc.avatar.getAvatarInfo surface an AvatarRow payload. V2 humans are tagged with CrcV2_RegisterHuman events and look like:

• avatar / tokenId – human avatars use their address as the ERC‑1155 token id.

• cidV0 – IPFS CID pointing to the profile JSON; cidV0Digest is the on-chain metadata digest.

• hasV1 – indicates whether the address has a legacy v1 identity that can still be migrated.

Creating V2 Human Avatars

1. Invite the new human – the inviter uses an existing HumanAvatar (fetched via Sdk#getAvatar) and escrows 100 CRC:

1. Register / accept invitation – the invitee calls sdk.register.asHuman. Pass either an existing CID or a Profile object; the SDK auto-pins profile objects to the Circles profile service before registering with the hub.

Working With Profiles

• avatar.profile.get() – fetches and caches the IPFS JSON referenced by cidV0.

• avatar.profile.update(profile) – pins new metadata and updates the NameRegistry digest; useful for avatar name/description/image changes.

• sdk.register.asHuman(inviter, profileOrCid) – automatically uses the Profiles service when a plain object is supplied, so invitees do not need prior CID knowledge.

Trust & Transfers

• Establish trust through avatar.trust.add('0xFriend...', expiry?), remove trust via avatar.trust.remove, and inspect relationships using avatar.trust.getAll() or avatar.trust.isTrusting.

• Transfer CRC with avatar.transfer.direct('0xRecipient...', 25n * 10n ** 18n) for simple paths, or avatar.transfer.advanced to opt into wrapped balances, token filters, or encoded metadata.

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.

Profile Data Model

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

1) getAvatar

Gets an avatar instance by address.

• Parameters:

Prerequisites

Make sure you’ve completed these before continuing.

• You’ve installed a wallet, or

ERC-1155

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.

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:

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).

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.

Get total balance (v1, v2)

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.

Get detailed token balances (v1, v2)

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.

Get transaction history

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.

Get trust relations

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.

Get aggregated trust relations

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.

Find groups

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:

Get group memberships

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.

Get invited users

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.

Get invited by

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.

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.