mcpField
U
use-circle-wallets

use-circle-wallets

github.com/circlefinDevelopment160975 installsUpdated 2w ago
Repository

About use-circle-wallets

An agent skill that helps developers choose among Circle wallet types based on custody, authentication, account type, and target chain. It recommends a type before handing implementation to the matching skill and performs no on-chain operations itself.

Key features

  1. 01Compare three Circle wallet types
  2. 02Choose by custody and authentication
  3. 03Filter by chain and account type
  4. 04Delegate implementation to matching skills
  5. 05Flag missing context and operational risks

Use cases

  1. 01Choose a custody model for a new app
  2. 02Select an account type for a target chain
  3. 03Confirm authentication and approval before implementation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/circlefin/skills --skill use-circle-wallets

After installing, type/use-circle-walletsin Claude Code to confirm it loaded.

Bundled filesreferences/example-scenarios.md

Details

From the project README

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-ControlledUser-ControlledModular (Passkey)
CustodyDeveloperUserUser
AuthAPI key + entity secret (backend)Social login / email OTP / PINPasskey (WebAuthn)
Account typesEOA, SCAEOA, SCAModular Wallet SCA (ERC-6900)
Gas sponsorshipSCA via Circle PaymasterSCA via Circle PaymasterCircle Paymaster or third-party paymaster
Custom modulesNoNoYes
ArchitectureBackend SDK onlyBackend + frontend SDKsFrontend 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

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.

Comments

Markdown supported