Use Modular Wallets

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):

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

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:

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.

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 with the same nonce).

Error Handling

Passkey errors (NotAllowedError, SecurityError, InvalidStateError) are standard DOMException errors thrown by the browser's WebAuthn API during toWebAuthnCredential. Wallet errors (155xxx) are returned by the Circle API. AA errors are ERC-4337 EntryPoint errors returned by the bundler. For the full error reference, see Error Codes. For debugging failed transactions, see Transaction States and Errors.