Circles
Mini App Developers
Mini apps are focused web experiences built around Circles.
There are two common ways to build one. In the smoother path, the user opens your app inside Circles MiniApp environment and signs with their Gnosis App passkey. In the more flexible path, the user scans a QR code and finishes the action in Gnosis App. The first route is more user-friendly, but it requires Circles host integration, SDK usage, and listing in the mini app store. The second route is easier to ship anywhere, but it adds a handoff step.
Two user journeys
Users either sign the action directly inside Circles with their Gnosis App passkey or scan a QR code and finish it in Gnosis App.
Direct signing feels smoother
Hosted mini apps keep people in one flow, but they require the Circles SDK and listing in the mini app store.
QR is easier to deploy
QR-based mini apps can run on almost any web page or shared screen without store listing, but they add one extra step for the user.
How it works
Start from the user experience you want
The main decision is simple: should users approve actions directly inside your mini app, or should they scan a QR code and continue in Gnosis App? That user-facing choice determines the integration work and distribution path.
Choose the user journey first
Decide whether people should sign directly inside Circles with their Gnosis App passkey or scan a QR code and continue in Gnosis App.
Implement the interaction
Hosted apps integrate with the Circles SDK and host bridge for signatures and transactions. QR apps render a QR payload, then watch for the resulting onchain action.
Decide how users discover it
Hosted mini apps can be listed in the Circles mini app store. QR-based flows can also live on shared screens, booths, or merchant pages without store distribution.
Developer resources
Start building or study live examples
Use the QR starter when you want a scan-first flow, study the Circles Miniapps repo when you want direct in-app signing, and follow the submission guide when your hosted app is ready for the store.
Boilerplate for QR-based miniapps
↗Use this starter when users scan a QR code and complete the action inside Gnosis App.
Circles Miniapps GitHub repo
↗Study the hosted mini app setup when you want users to sign actions directly inside Circles with their Gnosis App passkey.
How to submit miniapps
↗Follow this guide when your hosted mini app is ready to be listed in the Circles mini app store.
Two mini app patterns
Choose the interaction model that fits the context
The difference is mostly about what the user has to do at the moment of signing. Either they stay inside the mini app and approve with their Gnosis App passkey, or they scan a QR code and complete the action in Gnosis App.
Best for the smoothest user experience inside Circles
Hosted mini apps with direct signing
In this model, the user opens your mini app inside Circles and signs actions directly with their Gnosis App passkey. They do not need to switch devices or scan a code, so the flow feels more natural for repeat actions and deeper product journeys. The tradeoff is that you need the Circles SDK and a listing in the mini app store.
The user opens the app from the Circles mini app store or a hosted mini app URL.
Signatures and transactions are requested directly inside the Circles environment.
This is the more user-friendly route, but it depends on host integration and store distribution.
Best for booths, kiosks, shared screens, and quick launches
QR-initiated mini apps
This merch shop is an example of the QR route. Your app can run on a normal web page, kiosk, or public screen, and when the wallet step is needed it shows a QR code. The user scans it with Gnosis App and finishes the action there. That makes the setup more flexible because you do not need hosted mini app integration or store listing, but it is slightly less convenient for the user.
The screen displays a payment request or action as a QR code.
The user scans the QR with Gnosis App and confirms the transaction there.
The mini app watches for the resulting onchain action and updates the UI after settlement.