use-modular-wallets

Overview

Prerequisites / Setup

Installation

npm install @circle-fin/modular-wallets-core viem

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)

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

Transport URL Examples

toModularTransport

/arcTestnet

/polygonAmoy

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., localStorage) 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.

• 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

Rules

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. NEVER auto-execute fund 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.

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.