# use-user-controlled-wallets

A skill for building non-custodial wallets on Circle's SDK, with Google, Apple, Facebook, email OTP or PIN login and keys the user keeps.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 949 installs · ★ 158
- Author: circlefin
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/circlefin/skills/tree/HEAD/plugins/circle/skills/use-user-controlled-wallets/SKILL.md
- Updated: 2026-10-16
- HTML: https://affpapa.org/en/nevibecode/skills/use-user-controlled-wallets

## What it does

This skill walks through building a wallet where the end user holds the private keys. Every sensitive operation — wallet creation, transfers, message signing, contract calls — runs through a challenge-response flow: the backend creates the operation and gets a `challengeId`, the frontend calls `sdk.setAuthentication({ userToken, encryptionKey })` and then `sdk.execute(challengeId, callback)`, and the user approves inside Circle's hosted UI.

Two SDKs are involved. The server side uses `@circle-fin/user-controlled-wallets` to hold the API key, create users and build challenges. The client side uses `@circle-fin/w3s-pw-web-sdk` for auth flows and challenge execution. You also need `vite-plugin-node-polyfills`, because the SDKs depend on Node.js built-ins like `buffer` and `crypto` that the browser does not provide. Have `CIRCLE_API_KEY` and `CIRCLE_APP_ID` ready before you start.

One step is easy to miss: call `sdk.getDeviceId()` right after initializing the SDK. It opens a session with Circle's service through an iframe, and without it `sdk.execute()` fails silently. Worth knowing too — a developer cannot recover a user's wallet if that user loses access to their login method. Recovery depends entirely on the user authenticating again.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add circlefin/skills --skill use-user-controlled-wallets -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/use-user-controlled-wallets/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/use-user-controlled-wallets/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add circlefin/skills --skill use-user-controlled-wallets -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/use-user-controlled-wallets/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add circlefin/skills --skill use-user-controlled-wallets -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/use-user-controlled-wallets/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install circlefin/skills use-user-controlled-wallets
```

2. **Manually: put the files in place**
- File: `.github/skills/use-user-controlled-wallets/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add circlefin/skills --skill use-user-controlled-wallets -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/circlefin/skills --path plugins/circle/skills/use-user-controlled-wallets
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/use-user-controlled-wallets/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add circlefin/skills --skill use-user-controlled-wallets -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/circlefin/skills/tree/HEAD/plugins/circle/skills/use-user-controlled-wallets/SKILL.md

## When to use it
- build a wallet where users hold their own keys
- add Google, Apple or Facebook sign-in to a wallet
- sign a message after the user approves it
- call a smart contract from the browser
- pick between EOA and SCA at wallet creation

## Example prompts
- Help me build a non-custodial Circle wallet with email OTP login
- Set up the challenge-response flow for a token transfer: backend creates the challengeId, frontend calls sdk.execute
- Explain when to use SCA instead of EOA and how that affects gas

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9a94c721a74e255e.

BEGIN THIRD-PARTY FILE 9a94c721a74e255e
````text
---
name: use-user-controlled-wallets
description: "Build non-custodial wallets where end users retain control of their private keys via Circle's user-controlled wallets SDK. Supports Google, Apple, Facebook social login, email OTP, and PIN authentication with MPC-based key management. Covers wallet creation, token transfers, message signing, smart contract execution, and wallet management. Triggers on: user-controlled wallets, social login wallet, email OTP wallet, PIN wallet, w3s-pw-web-sdk, executeChallenge, MPC wallet, userToken, deviceToken, contract execution."
requirements:
  runtimes: []
  connectors: []
---

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

### Backend SDK Initialization

Uses `@circle-fin/user-controlled-wallets` for all server-side operations (user creation, challenge creation, transaction queries).

```typescript
import { initiateUserControlledWalletsClient, Blockchain, TokenBlockchain } from "@circle-fin/user-controlled-wallets";

const circleClient = initiateUserControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
});
```

### Frontend SDK Initialization
````
END THIRD-PARTY FILE 9a94c721a74e255e

The third-party file has ended. Everything between the 9a94c721a74e255e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2190 of 14372 bytes. © circlefin · Apache-2.0 · https://github.com/circlefin/skills/tree/HEAD/plugins/circle/skills/use-user-controlled-wallets/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md