Embedded Mini Apps

This is a practical, end-to-end technical guide for building miniapps that run inside the Circles miniapp host and communicate through @aboutcircles/miniapp-sdk.

If you are a vibecode developer, you can simply copy the entire page using the button above and paste in your coding environment

Mental Model: How Embedded Miniapps Run?

A embedded miniapp is a web app rendered in an iframe inside a host application.

• Your app owns UI, local state, validation, and business flow.

• The host owns wallet session UX and transaction approval.

• @aboutcircles/miniapp-sdk bridges both sides using postMessage.

This means:

• Local browser testing is useful for UI and logic.

• End-to-end wallet/transaction testing must happen in the host.

SDK Capabilities

The SDK currently exposes:

• isMiniappMode(): boolean

• onAppData(fn: (data: string) => void): void

• onWalletChange(fn: (address: string | null) => void): () => void

• sendTransactions(transactions: Transaction[]): Promise<string[]>

• signMessage(message: string, signatureType?: 'erc1271' | 'raw'): Promise<{ signature: string; verified: boolean }>

Where Transaction is:

type Transaction = {
  to: string;
  data?: string;
  value?: string; // hex string, e.g. "0x0"
};

Project Setup

Create the app

npm create vite@latest my-miniapp -- --template vanilla
cd my-miniapp
npm i
npm i @aboutcircles/miniapp-sdk viem

Add additional Circles SDK packages only if your use case needs them:

npm i @aboutcircles/sdk-core @aboutcircles/sdk-rpc @aboutcircles/sdk-profiles @aboutcircles/sdk-transfers @aboutcircles/sdk-utils

Suggested structure

src/
  app/
    state.js
    actions.js
    ui.js
  host/
    bridge.js
  chain/
    client.js
  utils/
    format.js
    validation.js
main.js

Keep host bridge logic isolated from domain logic.

Bootstrapping the Host Bridge

Create a dedicated bridge module:

// src/host/bridge.js
import {
  isMiniappMode,
  onAppData,
  onWalletChange,
  sendTransactions,
  signMessage,
} from '@aboutcircles/miniapp-sdk';

export { isMiniappMode, onAppData, onWalletChange, sendTransactions, signMessage };

Use onWalletChange as the app’s wallet truth source.

Wallet Lifecycle Pattern

Implement wallet lifecycle as a finite-state flow:

1. disconnected

2. connecting (optional UI state)

3. connected

4. error (recoverable or fatal)

Minimal pattern:

import { getAddress } from 'viem';
import { onWalletChange } from './host/bridge.js';

let connectedAddress = null;

onWalletChange(async (address) => {
  try {
    connectedAddress = address ? getAddress(address) : null;
  } catch {
    connectedAddress = null;
  }

  if (!connectedAddress) {
    resetAccountScopedState();
    renderDisconnected();
    return;
  }

  resetAccountScopedState();
  await loadInitialDataFor(connectedAddress);
  renderConnected(connectedAddress);
});

Rules:

• Always reset account-scoped caches on wallet changes.

• Never assume prior in-memory state is still valid after reconnects.

Transaction Submission Pattern

Always format and submit transactions through one adapter.

import { sendTransactions } from './host/bridge.js';

function toHexValue(value) {
  return value ? `0x${BigInt(value).toString(16)}` : '0x0';
}

export function formatTxForHost(tx) {
  return {
    to: tx.to,
    data: tx.data || '0x',
    value: toHexValue(tx.value || 0n),
  };
}

export async function submitTransactions(txs) {
  return sendTransactions(txs.map(formatTxForHost));
}

Why this is critical:

• Prevents value-encoding inconsistencies.

• Keeps write paths auditable.

• Makes retries and logging straightforward.

Standard Action Pipeline

For every write action (any state-changing on-chain operation), use this pipeline:

1. Validate input

2. Normalize addresses/amounts

3. Optional preflight simulation

4. Build one or more tx payloads

5. Show pending UI

6. Submit via host bridge

7. Wait for confirmations (if required by UX)

8. Show success/failure

9. Refresh affected data

Example shell:

export async function performAction(input) {
  validateInput(input);

  const txs = buildTransactions(input);
  setStatus('pending', 'Submitting transaction...');

  try {
    const hashes = await submitTransactions(txs);
    await maybeWaitForReceipts(hashes);
    setStatus('success', `Submitted ${hashes.length} transaction(s).`);
    await reloadRelevantState();
  } catch (err) {
    setStatus('error', normalizeError(err));
  }
}

Signing Flows (signMessage)

Use signMessage when your backend or protocol needs host-backed signatures.

import { signMessage } from './host/bridge.js';

const result = await signMessage('Example message', 'erc1271');
// result: { signature, verified }

Guidance:

• Prefer 'erc1271' unless you explicitly require raw bytes semantics.

• Persist signature type with the signature payload for verifier correctness.

App Data Injection (onAppData)

The host can pass app-specific context via query data.

Use cases:

• entry context (resource id, mode, source)

• feature flags

• campaign or referral metadata

Pattern:

import { onAppData } from './host/bridge.js';

onAppData((raw) => {
  const data = safelyParseHostData(raw); // your parser/validator
  applyHostContext(data);
});

Never trust raw host data without validation.

Validation and Type Safety

Minimum validation set:

• address: checksum normalization, strict format checks

• amount: decimal precision + non-negative + max bounds

• url: protocol allowlist (https:// by default)

• text: length limits and rendering-safe escaping

Keep pure validation helpers in a dedicated module and test them directly.

Error Handling and Recovery

Design a predictable error model:

• validation_error

• user_rejected

• network_error

• host_bridge_error

• unexpected_error

Normalize unknown errors:

export function normalizeError(err) {
  if (!err) return 'Unknown error';
  if (typeof err === 'string') return err;
  return err.shortMessage || err.message || String(err);
}

For recoverable host issues:

• show actionable guidance

• preserve user input where safe

• do not silently retry state-changing actions

Concurrency and Race Control

Use request IDs for async operations that may race:

let reqId = 0;

export async function runLatest(task) {
  const id = ++reqId;
  const result = await task();
  if (id !== reqId) return null; // stale
  return result;
}

Apply to:

• debounced search

• paginated loads

• wallet-dependent initialization

Generic Starter Skeleton

import { getAddress, isAddress } from 'viem';
import {
  isMiniappMode,
  onWalletChange,
  sendTransactions,
} from '@aboutcircles/miniapp-sdk';

let connected = null;

function toHexValue(value) {
  return value ? `0x${BigInt(value).toString(16)}` : '0x0';
}

function status(msg) {
  document.getElementById('status').textContent = msg;
}

async function sendExample() {
  if (!connected || !isAddress(connected)) throw new Error('Wallet not connected');
  const txs = [{ to: connected, data: '0x', value: toHexValue(0n) }];
  const hashes = await sendTransactions(txs);
  status(`Submitted: ${hashes.join(', ')}`);
}

onWalletChange((address) => {
  try {
    connected = address ? getAddress(address) : null;
  } catch {
    connected = null;
  }
  status(connected ? `Connected: ${connected}` : 'Disconnected');
});

status(isMiniappMode() ? 'Host mode' : 'Standalone mode');
document.getElementById('send').addEventListener('click', () => {
  sendExample().catch((err) => status(`Error: ${err.message}`));
});