Create a Circles Group using Group manager MiniApp

Circles Groups Manager helps you create and manage Circles groups from one place. You can use it to create a new group, update the group's profile, manage admins and members, review important addresses, convert collected fees, and send group tokens.

This guide is written for people using the deployed app inside the Circles MiniApp environment.

Who This App Is For

Use this app if you need to:

• create a new Circles group

• manage an existing group you control

• add or remove group members

• add another admin to the group

• update ownership or operational addresses

• convert group fees into group tokens

• send group tokens to a Circles user

Before You Start

Requirements

• a Gnosis App account

Important Things To Know

• Most actions in this app require an onchain transaction.

• Every important change should be reviewed carefully before you approve it.

• Group image uploads are processed automatically:

  • the original file must be 8 MB or smaller

  • the image is cropped to a square

  • the preview is compressed to 256x256

  • the final processed image must be under 150 KB

Opening the App

1. Open Circles Groups Manager from the Circles MiniApp.

2. Connect your wallet if prompted.

3. Wait until the status changes from Not connected to Connected.

If wallet connection fails, reconnect the same wallet and try again.

What You See First

After connecting, the app opens on the groups list.

This screen shows:

• groups owned directly by your connected wallet

• groups owned by owner Safes you control

Each group card shows:

• the group image if available

• the group name

• the ticker or fallback identifier

• the group address

• an Open button

If you have not created or connected any groups yet, the app shows No groups yet.

Main Navigation

From the groups list, you can:

• click + Create to create a new group

• click Open to manage an existing group

When a group is open, the app gives you four main areas:

• Members

• Treasury Operations

• Group Details

• Advanced

The group header also includes:

• Edit to open the profile editor

• Refresh to reload group data

• Switch Groups to go back to the groups list

Create a Group

Click + Create from the groups list.

Information You Need To Enter

• Name

• Ticker

• Description

You can also add:

• a group image

• an external link with label and URL

Rules For Group Creation

• Name is required.

• Name must be 19 characters or fewer.

• Ticker is required.

• Ticker must be 2 to 8 characters long.

• Ticker can only contain uppercase letters and numbers.

• Description is required.

How To Create The Group

1. Enter the group name.

2. Enter the ticker.

3. Add a short description explaining what the group is for.

4. Optionally upload an image.

5. Optionally add an external link.

6. Click Create Group.

7. Review the transaction flow and approve it.

Open a Group

Click Open on any group in the groups list.

When a group opens, the app loads the main group summary, including:

• group name and ticker

• group description

• group image

• member count

• affiliate count

• fee balance summary

• key group addresses

• total supply

This is the main hub for everything you do after the group is created.

Edit Group Details

Open a group, then click Edit.

This section lets you update:

• description

• image

• external link

How To Update The Profile

1. Change the description if needed.

2. Upload a new image if needed.

3. Add or update the external link if needed.

4. Click Save Profile.

5. Approve the transaction.

After the update, the group header refreshes with the new content.

External Link Behavior

The app supports one external link:

• a link label

• a link URL

Use this for a website, community page, docs page, or any destination that helps members understand the group.

Members

Open a group, then choose Members.

This screen is where you manage who is trusted by the group.

What You Can Do Here

• view members

• search for people or groups to add

• remove existing members

• move through pages of members

The app loads members in pages of 50.

Add a Member

You can add a member by searching for:

• name

• registered name

• Circles avatar address

Steps

1. Type at least two characters in the search box, or paste a full 0x... address.

2. If needed, enable Include v1 users.

3. Choose the correct result.

4. Click Add.

5. Approve the transaction.

Adding a member creates a trust relationship from the group to that avatar.

Remove a Member

1. Find the member in the list.

2. Click Remove.

3. Approve the transaction.

Removing a member revokes that trust relationship.

Useful Member Search Notes

• If you paste a valid address, the app lets you add it directly.

• If a result is already a member, the app marks it as already added.

• If nothing matches, the app shows No matches found.

Group Details

Open a group, then choose Group Details.

This screen is mainly for reference. It shows the important onchain addresses and technical details tied to the group:

• group address

• owner Safe

• treasury

• mint handler

• service

• fee collection

• group type

• total supply

Use this page when you want to verify which addresses are currently active before making a change.

Advanced

Open a group, then choose Advanced.

This area is for admin and configuration tasks.

It includes:

• current group admins

• add new admin

• update owner Safe

• update service address

• update fee collection address

• manage membership conditions

Group Admins

At the top of the Advanced screen, the app shows the current owners of the owner Safe. These are effectively the people who can control group-level admin actions.

Add a New Admin

You can add a new admin by:

• searching by name

• searching by address

• pasting a wallet address

Steps

1. Enter a name or address in Add new Group Admins.

2. Select the correct result, or paste the address directly.

3. Click Add New Admin.

4. Confirm the action.

5. Approve the transaction.

Important Limitation

The app only supports adding Safe owners when the owner Safe threshold is 1.

If the Safe uses a threshold greater than 1, the app will not allow this action.

Update Owner Safe

Use this when you want a different Safe to take control of the group.

When To Use It

• you are transferring control to a new Safe

• you are restructuring admin ownership

• the current owner Safe is no longer the correct controller

Steps

1. Expand the Advanced section inside the admin panel.

2. Paste the new owner Safe address.

3. Click Update Owner.

4. Review the warning carefully.

5. Approve the transaction.

This is a high-impact action because it changes who controls owner-level group settings.

Update Service Address

Use this only if you know exactly which service contract the group should reference.

Steps

1. Expand the Advanced section.

2. Paste the new service address.

3. Click Update Service.

4. Confirm the change.

5. Approve the transaction.

Update Fee Collection Address

Use this to define where fees for the group should accumulate.

Steps

1. Expand the Advanced section.

2. Paste the new fee collection address.

3. Click Update Fee Collection.

4. Approve the transaction.

If you enter the same address as the currently connected wallet, the app shows a warning because this is usually not the best operational setup.

Membership Conditions

Membership conditions are contract addresses that the group has enabled.

Use this feature if your group relies on additional rule contracts for membership logic.

Enable a Membership Condition

1. Paste the contract address.

2. Click Enable.

3. Approve the transaction.

Disable a Membership Condition

1. Paste the address of an active condition.

2. Click Disable.

3. Approve the transaction.

The app prevents:

• enabling the same condition twice

• disabling a condition that is not currently active

Treasury Operations

Open a group, then choose Treasury Operations.

This area has two main features:

• Convert Fees

• Send Token

Convert Fees

This feature converts balances held at the fee collection address into the group token by routing them to the mint handler.

What You See

• fee collection balance

• currently convertible amount

• amount input

• Max shortcut

When To Use It

Use this when fees have accumulated and you want to convert the available balance into the group's token.

Steps

1. Review the current fee collection balance.

2. Check how much is currently convertible.

3. Enter an amount, or click Max.

4. Click Convert Fees.

5. Approve the transaction.

Conversion Rules

• the group must have a valid fee collection address

• the group must have a mint handler

• the fee collection address must hold fee tokens

• the amount must be greater than zero

• the amount cannot exceed the convertible balance

If the button is disabled, the app currently does not detect a convertible fee balance.

Send Token

This feature sends the group token from the fee collection address to another Circles avatar using max-flow routing.

What You See

• available group-token balance

• recipient search

• amount input

• Max shortcut

When To Use It

Use this when you want to distribute group tokens to a person, member, or another Circles participant.

Steps

1. Enter a recipient name or 0x... address.

2. Select the correct result if needed.

3. Enter an amount, or click Max.

4. Click Send Token.

5. Approve the transaction.

Send Rules

• the group must have a valid fee collection address

• the recipient must resolve to a valid Circles avatar

• there must be a routable path through the trust graph

• the amount cannot exceed the current max transferable amount

How Max Works

• If you have not selected a recipient yet, Max fills the currently available group-token amount.

• If a recipient is selected, Max calculates the maximum amount that can actually be routed to that recipient.

If no route exists, the app will show that no routable amount is available.

Typical End-to-End Workflow

For most users, the normal flow looks like this:

1. Open the app in Circles and connect your wallet.

2. Create a new group.

3. Review the generated owner Safe and group details.

4. Update the profile so the group has a clear description and image.

5. Add any additional admins you want managing the group.

6. Add the first members.

7. Verify the fee collection address and other advanced settings if needed.

8. When fees accumulate, convert them into group tokens.

9. Send group tokens to recipients when needed.

Troubleshooting

Wallet Does Not Connect

• Make sure you opened the app inside the Circles MiniApp.

• Reconnect the same wallet and try again.

Group Creation Fails

Check that:

• your wallet is connected

• the name is not longer than 19 characters

• the ticker is 2-8 uppercase letters or digits

• the description is filled in

• you approved the full transaction flow

Image Upload Fails

Check that:

• the file is an image

• the source file is 8 MB or smaller

• the image can be processed and compressed

No Groups Appear

• you may not own any groups yet

• you may not control any owner Safes that currently own groups

• reconnect and reopen the app if the list seems stale

Cannot Add a New Admin

Check that:

• the address is valid

• the address is not already an owner

• the owner Safe threshold is 1

Cannot Convert Fees

Check that:

• the group has a valid fee collection address

• the group has a mint handler

• the fee collection address holds fee tokens

• the amount does not exceed the convertible amount

Cannot Send Tokens

Check that:

• the fee collection address is valid

• the recipient is a valid Circles avatar

• a routable trust path exists

• the amount does not exceed the max transferable amount

Safety Tips

• Always double-check pasted addresses before approving a transaction.

• Treat Update Owner as a high-impact action.

• Avoid using a personal wallet as the fee collection address unless that is intentional and you are sure of what you are doing.

• Only update the service address if you understand why the group should point to a different contract.