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
| Developer-Controlled | User-Controlled | Modular (Passkey) | |
|---|---|---|---|
| Custody | Developer | User | User |
| Auth | API key + entity secret (backend) | Social login / email OTP / PIN | Passkey (WebAuthn) |
| Account types | EOA, SCA | EOA, SCA | Modular Wallet SCA (ERC-6900) |
| Gas sponsorship | SCA via Circle Paymaster | SCA via Circle Paymaster | Circle Paymaster or third-party paymaster |
| Custom modules | No | No | Yes |
| Architecture | Backend SDK only | Backend + frontend SDKs | Frontend SDK only |
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
| Scenario | Decision | Skill |
|---|---|---|
| Payment backend, programmatic payouts, high TPS | Developer-controlled + EOA | use-developer-controlled-wallets |
| Consumer app with Google/Apple login, gasless UX | User-controlled + SCA on L2 | use-user-controlled-wallets |
| DeFi app with biometric auth, custom modules | Modular Wallet on L2 | use-modular-wallets |
| NFT marketplace on Ethereum L1 | User-controlled + EOA | use-user-controlled-wallets |
| AI agent, autonomous multi-chain transactions | Developer-controlled + EOA | use-developer-controlled-wallets |
Implementation Patterns
Once a wallet type has been determined, TRIGGER the corresponding skill:
- Developer-controlled ->
use-developer-controlled-walletsskill - User-controlled ->
use-user-controlled-walletsskill - Modular (Passkey) ->
use-modular-walletsskill
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, oruse-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.
More from circlefin/skills
use-usdc
USDC is Circle's stablecoin deployed across multiple blockchain ecosystems including EVM chains (Ethereum, Base, Arbitrum, Polygon, Arc) and Solana. Use this skill to check balances, send transfers, approve spending, and verify transactions. Triggers on: USDC balance, send USDC, transfer USDC, approve USDC, USDC allowance, verify USDC transfer, USDC contract address, USDC on Solana, Solana USDC, check balance, SPL token, Associated Token Account, ATA, ERC-20 USDC, parseUnits, formatUnits, 6 decimals, viem, @solana/kit.
146use-arc
Provide instructions on how to build with Arc, Circle's blockchain where USDC is the native gas token. Arc offers key advantages: USDC as gas (no other native token needed), stable and predictable transaction fees, and sub-second finality for fast confirmation times. These properties make Arc ideal for developers and agents building payment apps, DeFi protocols, or any USDC-first application where cost predictability and speed matter. Use skill when Arc or Arc Testnet is mentioned, working with any smart contracts related to Arc, configuring Arc in blockchain projects, bridging USDC to Arc via CCTP, or building USDC-first applications. Triggers: Arc, Arc Testnet, USDC gas, deploy to Arc, Arc chain, stable fees, fast finality.
140use-developer-controlled-wallets
Create and manage Circle developer-controlled wallets where the application retains full custody of wallet keys on behalf of end-users. Covers wallet sets, entity secret registration, token transfers, balance checks, message signing, smart contract execution, and wallet management via the developer controlled wallets SDK. Triggers on: developer-controlled wallets, dev-controlled wallets, create wallet, wallet set, entity secret, transfer tokens, check balance, EOA wallet, SCA wallet, initiateDeveloperControlledWalletsClient, createWalletSet, createWallets, custody wallet, sign message, sign transaction, sign typed data, contract execution, execute contract, call contract, wallet upgrade, derive wallet, estimate fee, accelerate transaction, cancel transaction.
138bridge-stablecoin
Build USDC bridging with Circle App Kit or standalone Bridge Kit SDK and Crosschain Transfer Protocol (CCTP). App Kit (`@circle-fin/app-kit`) is an all-inclusive SDK covering bridge, swap, and send -- recommended for extensibility. Bridge Kit (`@circle-fin/bridge-kit`) is a standalone package for bridge-only use cases. Neither requires a kit key for bridge operations. Supports bridging USDC between EVM chains, between EVM chains and Solana, and between any two chains on Circle Wallets (i.e Developer-Controlled Wallets or Programmable wallets). Use when: bridge USDC, setting up Bridge Kit adapters (Viem, Ethers, Solana Kit, Circle Wallets), handling bridge events, collecting custom fees, configuring transfer speed, or using the Forwarding Service. Triggers on: Bridge Kit, App Kit, bridge USDC, crosschain transfer, CCTP, move USDC between chains, @circle-fin/bridge-kit, @circle-fin/app-kit, adapter-viem, adapter-ethers, adapter-solana-kit, forwarding service, bridge routes.
134use-smart-contract-platform
Deploy, import, interact with, and monitor smart contracts using Circle Smart Contract Platform APIs. Supports bytecode deployment, template contracts (ERC-20/721/1155/Airdrop), ABI-based read/write calls, and webhook event monitoring. Keywords: contract deployment, smart contract, ABI interactions, template contracts, event monitoring, contract webhooks, bytecode, ERC-1155, ERC-20, ERC-721.
128use-gateway
Integrate Circle Gateway to hold a unified USDC balance across multiple blockchains and transfer USDC instantly (<500ms) via permissionless deposit, burn, and mint workflows. Available on 11 EVM chains + Solana (mainnet and testnet), plus Arc testnet. Use when: enabling chain-agnostic user experiences, low-latency or instant next-block finality is required, capital needs to be pooled across chains for greater capital efficiency, or building apps with consolidated crosschain balances. Triggers on: Gateway, unified balance, crosschain USDC, instant transfer, chain abstraction, Gateway Wallet, Gateway Minter, gatewayMint, burn intent, crosschain liquidity, payment routing, capital efficiency, permissionless transfer.
126