Circles Mini App Host

A SvelteKit app that hosts mini apps in iframes at https://<VITE_BASE_URL>/miniapps. Mini apps can request wallet transactions and message signing via a postMessage protocol.

---

Submitting Your App to the Marketplace

Apps are listed in static/miniapps.json. To add yours, open a Pull Request against master on aboutcircles/CirclesMiniapps.

This submission flow is for Embedded Mini Apps that should ship from this repository and appear in the Mini Apps marketplace.

For the full contribution guide, see:
https://docs.aboutcircles.com/miniapps/contribute-mini-apps

What should PR contain

Your PR must include the full application code that will run inside Circles Mini Apps.

At minimum, the PR should include:

• The mini app source code in this repository
• Any local assets required by the app
• A logo committed to this repository
• A new entry in static/miniapps.json
• Any setup notes or app-specific dependencies needed to build the repo

If the implementation lives elsewhere and the PR only adds an external URL, it will not be considered.

How the host works

The marketplace reads app metadata from static/miniapps.json.

When a user opens /miniapps/<slug>, the host loads the matching app inside an iframe.

For an embedded mini app, the url should point to a route served by this same repository, not to an external deployment.

Recommended pattern:

• Host wrapper route: /miniapps/<slug>
• Embedded app route in this repo: /apps/<slug>
• static/miniapps.json entry: "url": "/apps/<slug>"

Required file layout

Create the app under:

src/routes/apps/<slug>/

Field	Required	Notes
slug	yes	URL-safe, unique identifier. Becomes the path /miniapps/<slug>.
name	yes	Display name shown in the marketplace.
logo	yes	HTTPS URL of a square logo (SVG or PNG, min 64×64 px).
url	yes	HTTPS URL of your app. Must load in an iframe.
description	yes	Short description shown under the app name.
tags	yes	At least one category tag, e.g. ["defi"].
isHidden	no	If true, hides the app from the marketplace list. The app is still accessible via its direct URL /miniapps/<slug>. Omit or set to false to show the app normally.

PR checklist

• Entry added to static/miniapps.json with all required fields
• App loads over HTTPS and works inside an iframe
• Logo URL resolves to a valid image
• slug is unique (no duplicate in the existing JSON)
• PR title: feat: add <your app name>

The Circles team reviews and merges PRs on a best-effort basis.

---

Please Note:

If you only want to test your miniapps, you don't need to go through the below steps and run the environment locally. You can use Circles Playground.

Prerequisites

• Node.js 18+
• mkcert for local TLS certificates

---

1. Install mkcert

macOS:

brew install mkcert
mkcert -install

Linux:

sudo apt install libnss3-tools
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert
mkcert -install

Windows:

choco install mkcert
mkcert -install

---

2. Configure environment

Copy .env.example to .env and fill in your values:

cp .env.example .env

VITE_COMETH_API_KEY=your_cometh_api_key
VITE_PIMLICO_API_KEY=your_pimlico_api_key
VITE_BASE_URL=circles.gnosis.io

VITE_BASE_URL is used for page titles and the dev server hostname. It must match the TLS certificate and /etc/hosts entry below.

---

3. Generate TLS certificates

Run this from the project root, using your VITE_BASE_URL value:

mkcert circles-dev.gnosis.io

This produces two files in the current directory:

• circles-dev.gnosis.io.pem — certificate
• circles-dev.gnosis.io-key.pem — private key

These are gitignored and must be generated locally by each developer.

---

4. Add the host to /etc/hosts

The dev server binds to the hostname, so you need to point it to localhost.

macOS / Linux:

sudo sh -c 'echo "127.0.0.1 circles-dev.gnosis.io" >> /etc/hosts'

Windows — open C:\Windows\System32\drivers\etc\hosts as Administrator and add:

127.0.0.1 circles-dev.gnosis.io

---

5. Install dependencies

npm install

---

6. Run the dev server

sudo npm run dev

The app is now available at https://circles-dev.gnosis.io (port 443).

Your browser will trust the certificate because mkcert adds its CA to the system trust store.

---

Running example mini apps locally

The examples/ directory contains demo mini apps you can run alongside the host for testing.

Sign Message demo (port 5181):

npm run demo:sign

ERC20 Transfer demo (port 5180):

npm run demo:tx

To test locally, update static/miniapps.json to point the relevant app URL to http://localhost:518x/.

---

Mini apps

Apps listed in static/miniapps.json appear on the /miniapps page. See Submitting Your App for the full entry format.

URL patterns

URL	Description
/miniapps	App list
/miniapps/<slug>	Open a specific app directly
/miniapps/<slug>?data=<base64>	Open app and pass arbitrary data to it

Passing data to apps

The ?data= param carries arbitrary base64-encoded data to the mini app. The host decodes it and delivers it via a app_data postMessage. The mini app defines its own schema — plain strings, JSON, ABI-encoded bytes, etc.

Example — base64 JSON:

const data = btoa(JSON.stringify({ message: 'Please sign this', context: 'my-app:v1' }))
// use in URL: /miniapps/my-app?data=<data>

Example — ABI-encoded bytes (viem):

import { encodeAbiParameters } from 'viem'
const encoded = encodeAbiParameters(
  [{ type: 'string' }, { type: 'address' }],
  ['Hello', '0xABC...']
)
const data = btoa(encoded)

---

postMessage protocol

Mini apps communicate with the host via window.postMessage. Use examples/miniapp-sdk.js for a ready-made client-side SDK.

From mini app → host:

type	Payload	Description
request_address	—	Ask for the current wallet address
send_transactions	{ transactions: [{to, value?, data?}], requestId }	Request transaction approval
sign_message	{ message: string, requestId }	Request message signing

From host → mini app:

type	Payload	Description
wallet_connected	{ address }	Wallet is connected
wallet_disconnected	—	Wallet is not connected
app_data	{ data: string }	App-specific data from the ?data= URL param
tx_success	{ hashes, requestId }	Transactions sent
tx_rejected	{ reason, requestId }	Transaction rejected
sign_success	{ signature, verified, requestId }	Message signed
sign_rejected	{ reason, requestId }	Signing rejected

---

Wallet

Wallet connection uses Cometh Connect SDK with a Safe smart account and Pimlico as the paymaster on Gnosis Chain.

• Connecting triggers a passkey prompt via navigator.credentials.get() — the user picks their passkey and Cometh resolves the associated Safe address automatically
• No address input required — the Safe address is derived from the passkey
• On successful connect the address is saved to localStorage and restored on next visit without prompting the passkey again
• Disconnecting clears both the in-memory state and localStorage

---

Build

npm run build

Output goes to build/. It is a fully static site (SvelteKit adapter-static) with a 404.html fallback for client-side routing of dynamic slug routes.

Developer responsibilities

By submitting a mini-app for listing, you confirm that: Your app and its use of Circles / Gnosis tooling complies with all applicable laws and regulations in the jurisdictions . You have not introduced, and will not introduce, any malicious code, backdoors or other potentially technologically harmful content or software designed to compromise users’’ assets, rights, wallets or the Circles/Gnosis infrastructure, and you will take reasonable care in accordance with industry practice to avoid the existence of any bugs or vulnerabilities in the mini-apps you develop that could lead to loss of user funds or disruption to our systems. The Circles / Gnosis team may reject, de-list, disable or restrict the availability of any mini-app at any time, in its sole discretion, including where we suspect any legal or security risks, or where we have reason to believe you are engaging in abusive or prohibited behaviour.