Invitation Link Manager Mini App Guide
The Invitation Manager is a miniapp that lets you create shareable Circles invitation links, single-use codes that anyone can redeem to sign up with an invited Circles account, optionally also adding them to a particular group. You can group those codes into Magic Links (one shareable URL backed by many codes), pause and resume a campaign at any time, attach UTM tags, and manage the leftover codes in your personal pool.
This guide walks through every screen from the perspective of someone who just opened the app for the first time.
Before you start
You will need:
A Gnosis App account
Quota on the InvitationFarm contract (If you are a community/group manager, please reach out to us on TG)
1. Signing in
When you open the app you land on a card titled Invitation Manager with a short summary of what the tool does and a status line at the bottom.
The status reads Waiting for account connection… until the parent Circles app reports a wallet. Once it does, it changes to Connected: 0x1234…5678 and a Sign in button appears.
Click Sign in. The app fetches a one-time challenge from the Circles auth server and asks your wallet to sign it.
Approve the signature request in your wallet.
On success you land on the Magic Links tab.
2. The two tabs
Once signed in, you see two tabs across the top of every screen:
Magic Links — your shareable distribution links. Each magic link is a campaign that bundles many invite codes behind one URL.
Individual Links — your personal pool of raw invite codes that aren't currently attached to any magic link. Useful as a holding area, for codes you generated outside the app, or for codes that got pulled out of a deleted session.
Above the Magic Links list there is also a green banner reading Overall quota available: N invites. This is your remaining quota on the InvitationFarm contract, refreshed every time you load the tab. If it shows 0, generate buttons are hidden, but everything else still works.
3. Magic Links tab
Creating a new magic link
Click + New in the top-right of the Magic Links tab. The New Magic Link modal appears.
Enter a Label (optional, max 80 chars) — e.g.
ETHDenver booth #3. This is purely for your own reference and is never shown to invitees.Pick an Expires option: Never, 1 day, 7 days, or 30 days. After the chosen interval, the link stops accepting new claims (existing claims are unaffected). You can also pause and resume manually at any time, regardless of expiry.
Click Create Magic Link. The new link appears at the top of your list and the detail view opens automatically.
Click 🔗 Copy Link on any card. The button briefly changes to ✓ Copied for two seconds. The URL on your clipboard looks like:
Anyone with this URL can claim one invite code from the session, in the order they were added. You can hand the same URL to many people — each visitor gets a different code under the hood.
Adding URL parameters (UTM tags etc.)
Click ＋ Add parameters on a card to open the Add Parameters modal.
Enter a query string in key=value&key=value format — do not include the leading ?. Example:
These params are saved to your browser's local storage for that magic link and automatically appended to whatever URL the 🔗 Copy Link button copies next. The params are never sent to the server, so they will not appear if someone else views the same link from a different browser, and clearing your browser data wipes them.
The ＋ Add parameters button changes its style once params are present, so you can tell at a glance which links already have tracking attached.
4. Magic link detail view
Click any card in the Magic Links list (or finish creating a new one) to open the detail view.
4.1 The header bar
The header shows the label, the Active / Paused status, and the expiry summary (e.g. Expires in 5d or no expiry). On the right are four icon buttons:
⏸ / ▶ — pause or resume the session. While paused, the link is dead for new claimants; existing claims are not affected. Click again to resume.
↻ — refresh the session data and codes list from the server.
↪ — reassign the entire session to another wallet address (see 4.8).
🗑 — delete the session (see 4.9). This button has a red tint as a warning.
4.2 Generating new invite codes (quota required)
If your overall quota is greater than 0, a green bar appears just below the header reading Quota: N, with a number input (1–10) and a green ＋ button.
Set the number of codes you want to generate. The maximum per click is 10 or your remaining quota, whichever is lower.
Click ＋. The status line walks through several stages: generating keypairs, building transactions, waiting for wallet confirmation, adding to session, and (if a group is assigned) trusting in the group.
Your wallet asks you to approve two transactions:
Tx 1 — claim invite slots from the InvitationFarm contract. This consumes your quota.
Tx 2 — transfer the resulting invite tokens to the session's holder address.
The keys are stored on the referrals server and added to this session.
If you have a group assigned, the new accounts are trusted into that group automatically.
On success: Generated and added N invitations to this session. The quota counter drops accordingly.
4.3 Assigning a group
Below the header is a row reading Group: No group (or the group name if one is already set). Click the value to open the Assign Group modal.
The modal lists every Circles group you can act on:
Groups where your wallet is the owner or the service address, and
Groups owned by a Safe multisig that you are a signer on (your role is shown as the Safe's role; the Safe's address is shown in italics).
4.4 The invites list
Under the Invites heading you see one row per invite code attached to this session. Each row carries:
A truncated key preview like
0x1a2b3c…d5e6f7— that's the start and end of the private key. Codes are not shown in full anywhere in the UI.The derived account address in small grey text (when the address is known), so you can match a code to an on-chain account.
A status badge: queued (sitting in the session, ready to be handed out), dispatched (the URL has been opened by someone), or claimed (an invitee has successfully registered with it).
Two icon buttons on queued rows only: ↔ Reassign (move the code to another magic link) and ✕ (remove from this session). Dispatched and claimed codes have no actions — once a URL has been visited, the code is in the wild.
Codes are fetched in pages of 50; the app keeps loading until all of them are on screen, so there is no "load more" button. Claimed codes are collapsed under a N claimed invites toggle at the bottom; click it to expand them (claimed codes have no actions — they belong to real users now).
The header shows a running summary: N claimed, M dispatched, K total.
4.5 Per-code actions
↔ Reassign — opens the Move to another Magic Link modal listing your other active (non-paused) sessions. Click one to move just this code. Useful when you need to rebalance between campaigns. If the source session has a group assigned, that trust is left alone (the code is still trusted in the old group); reassign the group on the destination if you need different membership.
✕ — pulls the code out of this session entirely. The code is not destroyed — it returns to your pool on the Individual Links tab and can be reassigned later.
4.6 Adding codes manually
At the bottom of the codes list is a full-width + Add keys manually button. Click it to open a textarea.
Paste private keys, one per line, in 0x + 64 hex character format. Stray whitespace is fine; anything that doesn't match 0x[0-9a-fA-F]{64} is silently skipped.
Click Add Keys. The result line reports how many were:
Added — newly attached to this session.
Skipped (duplicate) — the same private key was already in your account.
Already claimed — the key has already been used to register a Circles account; it can't be reused.
If a group is assigned, the new accounts are trusted into the group as part of the same flow.
4.7 Pausing and resuming
Click the ⏸ button to pause a session. The status pill flips to Paused and the magic link URL becomes inactive and anyone who opens it sees a "this link is not active" message in the Circles app, even if there are still queued codes. Click ▶ to resume.
Pausing is purely a server-side flag; it costs no gas and is instantaneous.
4.8 Reassigning the session to another address
Click the ↪ button in the header. A blue input row appears: enter a 0x + 40-hex-character wallet address and click Reassign.
The address must validate; if it doesn't, the input border turns red. On success, a centred modal appears reading Session Reassigned with the new owner's address — click Done to return to the Magic Links list. The session no longer appears in your list; it's now owned by the recipient and they will see it when they sign in.
This is a server-side ownership transfer. It does not move the codes out from under you — the on-chain accounts behind each code are unchanged — but the new owner gains control over the session record (including its label, expiry, group assignment, and the ability to add or remove codes).
4.9 Deleting a session
Click the red 🗑 button. A confirmation row appears: Delete this session? This cannot be undone. with Delete and Cancel buttons.
Confirming triggers a multi-step cleanup:
Fetch every code in the session that is not yet claimed.
If a group is assigned, untrust those accounts from the group on chain (one or more wallet transactions, batched ~30 per tx).
Migrate the unclaimed codes back to your pool (best-effort — if this step fails, the codes are not lost on chain, but they may not surface in the Individual Links tab; they can still be reattached manually).
Delete the session record from the server.
Return you to the Magic Links list.
Claimed codes are deliberately left alone — they belong to real Circles accounts and deleting the session does not remove those accounts or their group memberships. If you want to fully revoke a claimed account from a group, you have to do that through the normal Circles group admin tools.
5. Individual Links tab
Switch to Individual Links in the top tab bar.
5.1 What this tab is for
This is your personal pool of invite codes that are not currently attached to any magic link. Codes land here when you:
Generate them externally and store them via the advanced add-keys panel (5.3).
Click ✕ on a code inside a session to pull it out (4.5).
Delete a session — its unclaimed codes migrate here (4.9).
Use it as a holding area, or as a way to bulk-attach a stockpile of codes to a magic link in one go.
5.2 What you see
The pool loads in pages of 50; the app keeps fetching automatically until everything is on screen. Each row has:
A checkbox for bulk selection.
The truncated key preview.
A Confirmed pill on codes that the referrals server has confirmed (this is just a freshness signal and both confirmed and unconfirmed codes are usable). Codes that are not yet confirmed show no pill.
Already-redeemed codes appear in a collapsed section at the bottom under a N claimed invites toggle, each with a faded Claimed pill and the derived account address. There are no per-row actions on this tab — bulk-assign (5.4) is the only operation.
A + Add keys manually (advanced) link sits above the list. The "advanced" tag is intentional: most people will never need to paste raw private keys.
5.3 Storing codes to your pool
Click + Add keys manually (advanced). A text area opens.
Paste private keys, one per line, in
0x+ 64 hex character format.Click Store Keys. Same parsing rules as the session manual-add (4.6); duplicates and already-claimed keys are reported in the result line.
The codes land in your pool immediately; they can then be attached to any magic link via 5.4.
5.4 Bulk-assigning to a magic link
Tick the checkboxes next to the codes you want to attach. To select every code currently rendered, use the Select all checkbox in the header row.
The right side of the header row shows Assign to magic link → with a count.
Click it to open the Assign to Magic Link modal — a list of your active (non-paused) sessions with their totals.
Click a session. The codes are attached to it, your selections clear, and the pool list refreshes.
If the target session has a group assigned, the newly attached codes are not automatically trusted — to do that, open the session detail and either re-pick the group (which retriggers trust on every code) or generate/add the codes directly from inside the session.
To move a code in the other direction (out of a magic link and back to this pool), use the ✕ button on the codes list inside the session detail.
6. What an invitee experiences
When you give someone a magic link, here is what happens on their end:
They open
https://circles.gnosis.io/invitation/<slug>(with whatever UTM tags you appended) in their browser.The Circles app picks the next queued code from your session and walks the visitor through onboarding as that pre-funded account. They do not need to bring their own wallet — the invite code itself is the private key for a fresh account, and Circles imports it into the user's session.
If the session has a group assigned, the visitor is automatically a trusted member of that group from day one.
The session's counts update: queued drops by one, dispatched / claimed go up.
If the link has been paused, has expired, or has no codes left, the Circles app shows the visitor an inactive-link message and no account is created.
7. Troubleshooting / FAQ
"No quota available to generate invitations."
Your address has no remaining slots on the InvitationFarm contract. Quota is allocated by the Circles team; you can still create magic links, attach codes you generated elsewhere, and reorganise existing codes. The Overall quota available banner at the top of the Magic Links tab is the source of truth.
Wallet popup never appears, or "Failed: …" during generate
The two-transaction generate flow (claim slot, then transfer tokens) is all-or-nothing. If you reject either popup, run out of xDAI for gas, or the wallet times out, nothing is added to the session and your quota is not consumed. Try again. If only the trust into group batches fail, the codes are in the session — just unscoped — and you can retry the trust by re-picking the group on the detail screen.
"No valid keys found. Keys must be 0x + 64 hex characters."
The textarea parser only accepts strings that match 0x followed by exactly 64 hex characters. Common causes: a stray 0x prefix is missing, the key has extra leading/trailing whitespace, or there are line breaks inside a single key. Each line is one key.
"Added N key(s). M skipped (duplicate)." / "M already claimed."
Skipped (duplicate) — the same private key is already attached to one of your sessions or sitting in your pool. No action needed.
Already claimed — the key has already been used to onboard a Circles account, so it can't be reused. Discard it.
Group assignment fails or only partly applies
Trust calls are batched ~30 accounts per transaction. If your wallet rejects a batch or you run out of xDAI mid-flow, the earlier batches succeeded but later ones did not. Refresh and re-pick the same group — already-trusted accounts will be no-ops, and the missing ones will be filled in. Safe-owned groups may also bounce if you don't have enough cosigner approvals on the underlying Safe.
My link shows as inactive to invitees
The session is paused, has expired, or has 0 queued codes. Check the status pill on the detail view and the queued count under the Invites heading. Resume with ▶, or generate / attach more codes.
"Reassign" address keeps getting rejected
The destination must be a valid Ethereum-style address: 0x followed by exactly 40 hex characters. The input box turns red on invalid input. Paste the address fresh, with no surrounding whitespace.
Delete didn't put my codes back in the pool
The migrate-back step is best-effort. If the network blip happens at exactly that moment, the on-chain accounts and private keys are still safe, but they may not appear in the Individual Links tab. You can re-add them via the advanced + Add keys manually (advanced) panel if you have a copy of the keys; otherwise they're effectively orphaned (the underlying Circles accounts continue to exist).
Sign-in fails
Two common cases: the wallet rejected the signature request (try again), or the auth server is unreachable (check auth.aboutcircles.com from your network). The signature is gas-free — if your wallet is asking for gas at this step, dismiss the request and retry; the next prompt should be a plain message-signing prompt.
Overall quota banner shows 0
You have no inviter slots allocated on the InvitationFarm contract. You can still:
Create magic links and attach codes you have manually.
Manage existing magic links (label, expiry, group, pause, copy URL, delete).
Use the Individual Links pool to stockpile and reassign codes between sessions.
To get quota allocated, reach out to us on TG .
The lookup-link panel returns nothing
The slug in the URL doesn't correspond to any current session — either it was mistyped, or the session has been deleted by its owner. Double-check the URL.
Last updated
Was this helpful?