/use-modular-wallets

name: use-modular-wallets
description: "Build crypto wallets using Circle Modular Wallets SDK with passkey authentication, gasless transactions, and extensible module architecture. Use when: creating crypto wallets with passkey-based (WebAuthn) registration and login, sending gasless transactions using Circle Gas Station paymaster, batching multiple transactions into a single user operation, implementing passkey recovery using BIP-39 mnemonic phrases, building advanced onchain wallets with custom modules (multisig, subscriptions, session keys). Triggers on: MSCA, passkey authentication, WebAuthn, paymaster, Gas Station, ERC-4337, ERC-6900, toCircleSmartAccount, toModularTransport, sendUserOperation, 2D nonce, passkey recovery, EIP-1193 provider."
requirements:
  runtimes: []
  connectors: []

Overview

Modular Wallets are flexible smart contract accounts (MSCAs) that extend functionality through installable modules. Built on ERC-4337 (account abstraction) and ERC-6900 (modular smart contract framework), they support passkey authentication, gasless transactions, batch operations, and custom logic modules (multisig, subscriptions, session keys). MSCAs are lazily deployed -- gas fees for account creation are deferred until the first outbound transaction.

Prerequisites / Setup

Installation

npm install @circle-fin/modular-wallets-core viem
# Passkey recovery also needs bip39:
npm install bip39

Environment Variables

Write or merge into the project's env file when scaffolding Modular Wallets:

# .env.local (Next.js) or .env (Vite)
# Paste your Client Key from Console → Keys → Client Keys (shown once; starts with TEST_API_KEY:)
NEXT_PUBLIC_CLIENT_KEY=
NEXT_PUBLIC_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl
VITE_CLIENT_KEY=
VITE_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl

Use the `NEXT_PUBLIC_*` pair for Next.js or the `VITE_*` pair for Vite — not both. Client URL is fixed — do not ask the user to copy it from Console. Chain paths (e.g. `/arcTestnet`) are appended in code via `toModularTransport`, not in the env var.

Before using the SDK, complete setup (see [Console Setup](https://developers.circle.com/wallets/modular/console-setup.md)):

1. Install the SDK and set the client env vars (see Installation and Environment Variables above). 2. In Console → Keys → Client Keys, create a Client Key. 3. Configure the Passkey Domain (passkeys are domain-bound).

Quick Reference

Supported Chains

| Chain | Mainnet | Testnet | | --- | --- | --- | | Arc | Yes | Yes | | Arbitrum | Yes | Yes | | Avalanche | Yes | Yes | | Base | Yes | Yes | | Monad | Yes | Yes | | Optimism | Yes | Yes | | Polygon | Yes | Yes | | Unichain | Yes | Yes |

For the latest supported blockchains: https://developers.circle.com/wallets/account-types.md (MSCA chain restrictions are in Rules below.)

Transport URL Path Segments

The `toModularTransport` URL requires the chain path segment appended to the client URL:

| Chain | Mainnet Path | Testnet Path | | --- | --- | --- | | Arbitrum | `/arbitrum` | `/arbitrumSepolia` | | Arc | `/arc` | `/arcTestnet` | | Avalanche | `/avalanche` | `/avalancheFuji` | | Base | `/base` | `/baseSepolia` | | Monad | `/monad` | `/monadTestnet` | | Optimism | `/optimism` | `/optimismSepolia` | | Polygon | `/polygon` | `/polygonAmoy` | | Unichain | `/unichain` | `/unichainSepolia` |

Example: `toModularTransport(\`${clientUrl}/polygonAmoy\`, clientKey)` for Polygon Amoy testnet.

Core Concepts

• **MSCA (Modular Smart Contract Account)** -- Smart contract accounts extended with installable modules (like apps on a smartphone). Ownership can be single owner, multi-owner, passkeys, or multi-sig.
• **Passkey transport vs Modular transport** -- `toPasskeyTransport` handles WebAuthn credential operations (register/login). `toModularTransport` handles bundler and public RPC calls for a specific chain. They are separate transports with different purposes.
• **Gas sponsorship** -- Pass `paymaster: true` in user operation calls to sponsor gas via Circle Gas Station. End users pay zero gas fees.
• **Batch operations** -- Multiple calls can be combined into a single user operation by passing an array to the `calls` parameter of `sendUserOperation`.
• **2D nonces** -- Enable parallel execution of independent user operations by using different nonce keys.
• **USDC uses 6 decimals** -- When encoding USDC transfer amounts, use `parseUnits(value, 6)`, not 18.
• **Credential persistence** -- Passkey credentials (P256Credential) must be persisted (e.g., httpOnly cookies) and restored on reload to maintain the user session.

Implementation Patterns

> **Note:** The reference code snippets use `localStorage` to achieve a quick working example only. Do not use `localStorage` in production.

READ the corresponding reference based on the user's request:

• `references/circle-smart-account.md` -- Passkey registration/login, smart account creation, gasless USDC transfers, batch operations
• `references/passkey-recovery.md` -- BIP-39 mnemonic recovery setup and execution when a passkey is lost

User Operation Lifecycle

User operations submitted via `sendUserOperation` follow an asynchronous state machine. The SDK's `waitForUserOperationReceipt` handles polling automatically. To query states directly, use the [List User Operations API](https://developers.circle.com/api-reference/wallets/buidl/list-user-ops.md).

**Happy path:** `SENT` -> `CONFIRMED` -> `COMPLETE`

**States:**

• `SENT` -- Submitted to the bundler, awaiting inclusion in a block.
• `CONFIRMED` -- Included in a block, awaiting finality.
• `COMPLETE` -- Finalized on-chain.
• `FAILED` -- User operation reverted or encountered an unrecoverable error. Check `errorReason` and `revertReason`.

**Error reasons on `FAILED`:**

• `FAILED_ON_CHAIN` -- Transaction reverted during blockchain execution.
• `FAILED_REPLACED` -- User operation was replaced (e.g., by a higher-fee operation