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.

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.

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.

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.

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.

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 V2 Core Components

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

• Now, your invitee can accept the invitation / register 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.

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

• Automatically checks the correct hub version based on

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

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.

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.

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.

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:

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:

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

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

Groups support following CRC token operations:

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

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

Understanding purpose of Groups

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.

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.

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

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

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.

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.

Circles SDK :

To use the Circles sdk, install the primary npm package

Features:

Base Groups are capable of following:

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

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

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

Get Total Supply for a Base Group

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

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.

Subscribe

To subscribe, you need an initialized CirclesData class.

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

const circlesRpc = new CirclesRpc("https://static.94.138.251.148.clients.your-server.de/rpc/"

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

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

Query past events

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

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

Event types

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.

Key Characteristics

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:

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.

💡 Query Circles Profiles

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

• Create new user profiles

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

Methods

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

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

Parameters (FindPathParams)

• from (Address, required): Source avatar.

• to (Address, required): Destination avatar.

• targetFlow (bigint, required for findPath

findPath (targeted route)

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.

findMaxFlow (ceiling)

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.

Advanced usage

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

From path to execution

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

Pathfinder helper functions (when you build flows yourself)

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

Error handling & tips

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

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.

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.

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

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.

For groups, GroupProfile extends Profile with a required symbol property so downstream tools can display the token ticker alongside other metadata.

Creating & Pinning Profiles

The SDK automatically creates a Profiles client using the profileServiceUrl from circlesConfig. You can call it directly when building forms or admin panels:

If you already know the CID (for example, you pinned it off-chain), you can fetch it later via await sdk.profiles.get(cid) or through any avatar instance using await avatar.profile.get().

Updating On-Chain Metadata

For avatars you control:

1. Pin the JSON: const cid = await avatar.profile.update(profileData);

2. The helper converts the CIDv0 into the bytes32 digest (cidV0ToHex) and submits nameRegistry.updateMetadataDigest.

3. Subsequent reads pull the updated profile, and you can register short names via

You can also skip the pinning step when you already have a CID:

Group Profiles and Registration

Group metadata uses the same pinning flow, but the registration step also needs the group symbol and deployment parameters for the BaseGroup factory. The SDK’s register.asGroup helper wraps all of that:

register.asGroup pins the groupProfile, deploys the BaseGroup via core.baseGroupFactory, extracts the new group address from the BaseGroupCreated event, and returns a BaseGroupAvatar wired to your runner.

Preview Image Requirements

When you embed an image as previewImageUrl, the profile service enforces a few constraints to keep responses lightweight:

• Format: PNG, JPEG, or GIF.

• Dimensions: exactly 256×256 pixels.

• File size: ≤ 150 KB after compression.

Here’s a browser-friendly helper that crops and compresses user uploads before pinning:

Profiles that violate those constraints are rejected by the pinning service, so validate on the client and surface helpful errors to your users.

Reading Profiles Back

• Via avatars: await avatar.profile.get() pulls and caches the current metadata, while avatar.profile.update handles write flows.

• Via RPC: CirclesRpc.avatar.getAvatarInfo includes the cidV0 so you can fetch profile blobs without instantiating an avatar class.

Because the CID is stored on-chain, any tool that knows the avatar address can look up its metadata by combining RPC data with the profile service.

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:

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.

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.

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.

See also:

Externally-Owned Account

An externally-owned account (also known as EOA) is one of the two types of Ethereum accounts. A private key controls it; it has no code, and users can send messages by creating and signing Ethereum transactions.

See also:

• on ethereum.org

• on ethereum.org

Gasless Transaction

Gasless transactions (also known as meta-transactions) are Ethereum transactions that are executed by a third party called on behalf of a to abstract the use of gas. Users must sign a message (instead of the transaction itself) with information about the transaction they want to execute. A relayer will create the Ethereum transaction, sign and execute it, and pay for the gas costs. The main benefit is that users can interact with the blockchain without holding the native token in their account.

See also:

• on docs.safe.global

Network

A blockchain network is a collection of interconnected computers that utilize a blockchain protocol for communication. Decentralized networks allow users to send transactions, that are processed on a distributed ledger with a consensus mechanism ensuring the batching, verification, and acceptance of data into blocks. This structure enables the development of applications without the need for a central authority or server.

See also:

• on ethereum.org

Owner

A Safe owner is one of the accounts that control a given Safe. Only owners can manage the configuration of a Safe and approve transactions. They can be either or . The of a Safe defines how many owners need to approve a Safe transaction to make it executable.

See also:

• on github.com

Relayer

A relayer is a third-party service acting as an intermediary between users' accounts and . It executes transactions on behalf of users and covers the associated execution costs, which may or may not be claimed.

See also:

• on docs.gelato.network

Safe Wallet

Safe is a smart contract wallet that requires a minimum number of people to approve a transaction before it can occur (M-of-N). If for example you have 3 main stakeholders in your business, you are able to set up the wallet to require approval from 2 out of 3 (2/3) or all 3 people before the transaction is sent. This assures that no single person could compromise the funds.

See also:

Smart Account

A smart account (also known as a smart contract account) leverages the programmability of smart contracts to extend its functionality and improve its security in comparison with . Smart accounts are controlled by one or multiple externally-owned accounts or other smart accounts, and all transactions have to be initiated by one of those.

Some common features that smart accounts offer to their users are:

• Multi-signature scheme

• Transaction batching

• Account recovery

Safe is one of the most trusted implementations of a smart account.

Transaction

A transaction is an action initiated by an to update the state of the EVM network. Transaction objects must be signed using the sender's private key, require a fee, and be included in a validated block.

A Safe transaction is a transaction sent to a Safe Proxy contract calling the method.

See also:

• on ethereum.org

Threshold

The threshold of a Safe account is a crucial configuration element that enables using Safe as a multi-signature smart account. It defines the number of required confirmations from the Safe owners a (Safe) transaction must have to be executable.

See also:

• and of a Safe with the Safe{Core} SDK on docs.safe.global

Wallet

A wallet is an interface or application that gives users control over their blockchain account. Wallets allow users to sign in to applications, read their account balance, send transactions, and verify their identity.

See also:

• on ethereum.org

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)

Sdk methods

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

CirclesData (sdk.data)

Read-only convenience interface:

• getAvatar(address) → AvatarInfo | undefined

• getTrustRelations(address) → AggregatedTrustRelation[]

ContractRunner (required for writes)

Minimal contract runner the SDK expects when sending transactions:

• address (sender)

• publicClient (viem client for reads)

• init(): Promise<void>

Avatar interfaces (shared across Human/Organisation/BaseGroup)

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

balances

• getTotal() → total CRC

• getTokenBalances() → TokenBalanceRow[]

• getTotalSupply() → BigInt (not implemented for all types)

trust

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

• remove(avatar | avatar[])

• isTrusting(address) / isTrustedBy(address)

profile

• get() → Profile | undefined

• update(profile) → cid

• updateMetadata(cid)

history

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

transfer

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

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

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

wrap

• asDemurraged(avatarAddress, amount) → tx receipt

• asInflationary(avatarAddress, amount) → tx receipt

• unwrapDemurraged(wrapperAddress, amount) → tx receipt

events

• subscribeToEvents() → sets avatar.events observable

• unsubscribeFromEvents()

• events → observable stream of Circles events

Human Avatar specifics

personalToken

• getAvailableAmount() → mintable CRC

• mint() → tx receipt

• stop() → tx receipt (irreversible)

groupToken (aliases to group in HumanAvatar)

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

• getMaxMintableAmount(group) → bigint

• redeem(group, amount)

Organisation Avatar specifics

Same groupToken surface as HumanAvatar; lacks personal minting.

BaseGroup Avatar specifics

groupToken (group operations)

• mint(group, amount)

• getMaxMintableAmount(group)

• redeem(group, amount)

base group admin (inherited from CommonAvatar group alias)

• setProperties.memberRequirement(group, newRequirement)

• setProperties.baseName(group, name, symbol)

Notes

• 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

1) getAvatar

Gets an avatar instance by address.

• Parameters: