use-circle-wallets — Claude Code skill: pick the right Circle wallet

---
name: use-circle-wallets
description: "Choose and implement the right Circle wallet type for your application. Compares developer-controlled, user-controlled, and modular (passkey) wallets across custody model, key management, account types, blockchain support, and use cases. Use whenever blockchain wallet integrations are required for onchain application development. Triggers on: which wallet, choose wallet, wallet comparison, EOA vs SCA vs Modular Wallet, custody model, programmable wallets."
requirements:
  runtimes: []
  connectors: []
---

## 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

1. **Who controls the keys / who is the custodian?**
   - Developer controls -> Developer-controlled wallets -> step 3
   - End user controls -> step 2
2. **Auth method?**
   - Passkey (WebAuthn biometric) with extensible modules -> Modular wallets -> step 4
   - Social login, email OTP, or PIN -> User-controlled wallets -> step 3
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
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

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](https://developers.circle.com/wallets/account-types)
- [Choosing Your Wallet Type](https://developers.circle.com/wallets/infrastructure-models)
- [Key Management](https://developers.circle.com/wallets/key-management)
- [Circle Developer Docs](https://developers.circle.com/llms.txt) -- **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](https://console.circle.com/legal/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](https://github.com/circlefin/skills/blob/master/README.md).