use-circle-wallets

Overview

Circle offers three wallet types -- developer-controlled, user-controlled, and modular -- each with different custody models, account types, key management, and capabilities. This skill helps you pick the right one.

Quick Comparison

Decision Guide

For the latest supported account types on different blockchains: https://developers.circle.com/wallets/account-types

For the latest supported features on different blockchains: https://developers.circle.com/wallets/supported-blockchains

Step 1 -- Who controls the keys / who is the custodian?

• Developer controls -> Developer-controlled wallets -> Step 3
• End user controls -> Step 2

Step 2 -- Auth method?

• Passkey (WebAuthn biometric) with extensible modules -> Modular wallets -> Step 4
• Social login, email OTP, or PIN -> User-controlled wallets -> Step 3

Step 3 -- Account type?

• Solana, Aptos, or NEAR -> EOA (only option)
• Ethereum mainnet -> EOA (SCA gas costs prohibitive, Modular Wallet not supported)
• L2 (Arbitrum, Base, Polygon, Optimism, etc.) -> EOA if max TPS needed; SCA if gas sponsorship or batching needed; Modular Wallet if passkey or other modular plugins needed

Step 4 -- Chain check (Modular wallets)

• Supported: Arbitrum, Avalanche, Base, Monad, Optimism, Polygon, Unichain
• NOT supported: Ethereum, Solana, Aptos, NEAR. Fall back to user-controlled wallets with SCA.

Example Scenarios

Implementation Patterns

Once a wallet type has been determined, TRIGGER the corresponding skill:

• Developer-controlled -> use-developer-controlled-wallets skill
• User-controlled -> use-user-controlled-wallets skill
• Modular (Passkey) -> use-modular-wallets skill

Strict Rules

• ALWAYS select the wallet type before starting implementation using the comparison table and decision guide above.
• ALWAYS use EOA on Ethereum mainnet (SCA gas prohibitive, Modular Wallet not supported) and on Solana, Aptos, NEAR (SCA/Modular Wallet not available).
• ALWAYS prefer SCA or Modular Wallet on L2 chains (Arbitrum, Base, Polygon, Optimism, etc.) when gas sponsorship or batch operations are needed.
• NEVER mix wallet types in a single user flow -- pick one and use its corresponding skill.
• ALWAYS delegate to the specific wallet skill (use-developer-controlled-wallets, use-user-controlled-wallets, or use-modular-wallets) for implementation.

Reference Links

• Account Types
• Choosing Your Wallet Type
• Key Management
• 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.