🔐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

For passkey recovery, also install:

npm install bip39

Environment Variables

CLIENT_KEY=     # Circle Console client key for app identification
CLIENT_URL=     # Circle Client URL (e.g., https://modular-sdk.circle.com/v1/rpc/w3s/buidl)

Before using the SDK, complete the Console Setup:

1. Create a Client Key in the Circle Console
2. Configure the Passkey Domain (passkeys are domain-bound)
3. Retrieve the Client URL

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.

Rules

Security Rules are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. Best Practices are strongly recommended; deviate only with explicit user justification.

Security Rules

• NEVER hardcode, commit, or log secrets (client keys, private keys). ALWAYS use environment variables or a secrets manager. Add .gitignore entries for .env* and secret files when scaffolding.
• ALWAYS store mnemonic recovery backups outside the repository root. NEVER commit recovery phrases to version control.
• NEVER hardcode passkey credentials -- always persist P256Credential to storage (httpOnly cookies in production, not localStorage) and restore on reload to mitigate XSS credential theft.
• NEVER reuse a recovery mnemonic phrase across multiple accounts.
• ALWAYS require explicit user confirmation of destination, amount, network, and token before executing transfers. MUST receive confirmation for funding movements on mainnet.
• ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
• ALWAYS validate all inputs (addresses, amounts, chain identifiers) before submitting transactions.
• ALWAYS warn before interacting with unaudited or unknown contracts.

Best Practices

• ALWAYS read the correct reference files before implementing.
• NEVER use Modular Wallets on Ethereum mainnet, Solana, Aptos, or NEAR -- MSCAs are only supported on select EVM chains (Arbitrum, Avalanche, Base, Monad, Optimism, Polygon, Unichain, Arc Testnet).
• ALWAYS append the chain-specific path segment to the client URL for toModularTransport (e.g., ${clientUrl}/polygonAmoy).
• ALWAYS use parseUnits(value, 6) for USDC amounts (6 decimals, not 18).
• ALWAYS pass paymaster: true to sponsor gas via Circle Gas Station.
• ALWAYS complete Circle Console Setup (client key, passkey domain, client URL) before using the SDK.
• ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
• ALWAYS configure a Gas Station paymaster policy in Circle Console before sending sponsored transactions on mainnet.
• ALWAYS update transport URLs from testnet path segments (e.g., /polygonAmoy) to mainnet equivalents (e.g., /polygon) when migrating to production.
• ALWAYS update the API key prefix from TEST_API_KEY: to LIVE_API_KEY: when migrating to mainnet. Testnet keys cannot be used with mainnets.
• ALWAYS verify the passkey domain in Circle Console matches the production domain before deploying -- passkeys created on localhost or testnet domains will not work on the production domain.

Alternatives

• Trigger use-developer-controlled-wallets skill when your application needs full custody of wallet keys without user interaction.
• Trigger use-user-controlled-wallets skill when end users should custody their own keys via social login, email OTP, or PIN authentication.

Reference Links

• Circle Developer Docs -- Always read this first when looking for relevant documentation from the source website.

DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.