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

1. Who controls the keys / who is the custodian?

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

1. Auth method?

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

1. 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

1. 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

READ references/example-scenarios.md for common scenarios mapped to a wallet-type decision and the skill to implement it.

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.

Safety & Escalation

This skill only recommends a wallet type; it performs no on-chain writes, transfers, signing, or key operations itself. Every side effect — creating a wallet, signing, sending funds, deploying a contract — happens in the delegated implementation skill, which owns confirmation for those actions.

Escalate before delegating when:

• Missing context — the custody model, target chain, or auth method is unclear. Ask the user; do not guess a wallet type.
• Missing access — the user lacks a Circle account, an API key + entity secret (developer-controlled), or a configured passkey domain (modular). Direct them to set that up first.
• Unsafe effects — the selected path will move real funds on mainnet. Flag that the implementation skill must obtain explicit user confirmation before any mainnet transaction.
• User approval — confirm the chosen wallet type with the user before handing off to the implementation skill.

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.