Use User Controlled Wallets

Overview#

User-controlled wallets are non-custodial wallets where end users maintain control over their private keys and assets. Users authorize all sensitive operations (transactions, signing, wallet creation) through a challenge-response model that ensures user consent before execution. Multi-chain support includes EVM chains, Solana, and Aptos.

Prerequisites / Setup#

Installation#

bash

npm install @circle-fin/user-controlled-wallets@latest @circle-fin/w3s-pw-web-sdk@latest vite-plugin-node-polyfills

Vite Configuration#

The SDKs depends on Node.js built-ins ( buffer, crypto, etc.) that are not available in the browser. Add vite-plugin-node-polyfills to your Vite config:

typescript

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { nodePolyfills } from "vite-plugin-node-polyfills";

export default defineConfig({
  plugins: [react(), nodePolyfills()],
});

Environment Variables#

bash

# Backend
CIRCLE_API_KEY=          # Circle API key

# Frontend
CIRCLE_APP_ID=           # App ID from Wallets > User Controlled > Configurator

Core Concepts#

Account Types#

User-controlled wallets support EOA and SCA account types, chosen at wallet creation.

EOA (Externally Owned Account): No creation fees, higher TPS, broadest chain support (EVM, Solana, Aptos). Requires native tokens for gas on EVM chains. Gas sponsorship only available on Solana via feePayer.

SCA (Smart Contract Account): ERC-4337 account abstraction. Gas sponsorship via Circle Gas Station paymaster, batch operations, flexible key management. EVM-only (no Solana/Aptos). First outbound transaction incurs gas for lazy deployment. Avoid on Ethereum mainnet due to high gas -- use on L2s (Arbitrum, Base, Polygon, Optimism).

For supported blockchains by account type: https://developers.circle.com/wallets/account-types

Full-Stack Architecture#

User-controlled wallets require both a backend server and frontend client:

1. Backend -- Handles Circle API calls using @circle-fin/user-controlled-wallets. The API key lives here.
2. Frontend -- Handles user interaction using @circle-fin/w3s-pw-web-sdk. Executes challenges and manages auth flows.

Challenge-Response Model#

All sensitive operations (wallet creation, transactions, signing) follow this pattern:

1. Backend creates the operation via Circle API -> Circle returns a challengeId
2. Frontend calls sdk.setAuthentication({ userToken, encryptionKey }) then sdk.execute(challengeId, callback) -> user approves via Circle's hosted UI
3. Callback fires with result or error

Authentication Methods#

MethodConsole SetupHow userToken Is ObtainedPINNoneBackend calls createUserToken({ userId }) (60 min expiry)Email OTPSMTP configSDK login callback after OTP verificationSocial LoginOAuth client IDSDK login callback after OAuth redirect

Implementation Patterns#

Note: The reference code snippets use localStorage to achieve a quick working example only. Do not use localStorage in production.

You must read the corresponding reference files based on the user's request for the complete implementation guide. Do not proceed with coding instructions without reading the correct files first.

• Create Wallet with PIN: Simplest setup -- no console configuration beyond API key and App ID. Users set a PIN and security questions through Circle's hosted UI. READ references/create-wallet-pin.md.

• Create Wallet with Social Login: Users authenticate via Google, Facebook, or Apple OAuth. Requires OAuth client ID configured in Circle Console. READ references/create-wallet-social-login.md.

• Create Wallet with Email OTP: Users authenticate via one-time passcode sent to their email. Requires SMTP configuration in Circle Console. READ references/create-wallet-email-otp.md.

• Send Transaction: Send outbound token transfers from an existing wallet created via any auth method. READ references/send-transaction.md.

Error Handling#

Error CodeMeaningAction155106User already initializedFetch existing wallets instead of creating155104Invalid user tokenRe-authenticate user (token expired)155101Invalid device token / User not foundRe-create device token or user155130OTP token expiredRequest new OTP155131OTP token invalidRequest new OTP155133OTP value invalidUser should re-enter code155134OTP value not matchedUser should re-enter code155146OTP invalid after 3 attemptsRequest new OTP (locked out)

Rules#

Security Rules are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. Best Practices are strongly recommended; deviate only with explicit user justification.

Security Rules#

• NEVER hardcode, commit, or log secrets (API keys, encryption keys). ALWAYS use environment variables or a secrets manager. Add .gitignore entries for .env* and secret files when scaffolding.
• ALWAYS implement both backend and frontend. The API key MUST stay server-side -- frontend-only builds would expose it.
• ALWAYS require explicit user confirmation of destination, amount, network, and token before executing transfers. NEVER auto-execute fund movements on mainnet.
• ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
• ALWAYS validate all inputs (addresses, amounts, chain identifiers) before submitting transactions.
• ALWAYS warn before interacting with unaudited or unknown contracts.
• ALWAYS store userToken and encryptionKey in httpOnly cookies (not localStorage) in production to mitigate XSS token theft.

Best Practices#

• ALWAYS read the correct reference files before implementing.
• ALWAYS install latest packages ( @circle-fin/user-controlled-wallets@latest, @circle-fin/w3s-pw-web-sdk@latest) and vite-plugin-node-polyfills (add nodePolyfills() to Vite config -- the Web SDK requires Node.js built-in polyfills).
• ALWAYS call sdk.getDeviceId() after init and sdk.setAuthentication({ userToken, encryptionKey }) before sdk.execute(). Without getDeviceId(), execute silently fails.
• NEVER use SCA on Ethereum mainnet (high gas). Use EOA on mainnet, SCA on L2s.
• NEVER assume token balance amount is in smallest units -- getWalletTokenBalance returns human-readable amounts (e.g., "20" for 20 USDC).
• ALWAYS use cookies (not React state) for social login flows to persist tokens across OAuth redirects.
• ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.

Alternatives#

• Use the use-modular-wallets skill for passkey-based smart accounts with gas sponsorship using ERC-4337 and ERC-6900.
• Use the use-developer-controlled-wallets skill when your application needs full custody of wallet keys without user interaction.

Reference Links#

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