# use-developer-controlled-wallets

A skill for Circle developer-controlled wallets: create wallet sets, move tokens, sign messages and run contract calls through the Wallets SDK.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 969 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-developer-controlled-wallets/SKILL.md
- Updated: 2026-10-16
- HTML: https://affpapa.org/en/nevibecode/skills/use-developer-controlled-wallets

## What it does

This skill covers the case where your app owns the keys and acts for end users. Keys sit behind an entity secret — a 32-byte hex value that gets encrypted with Circle's public key and registered once. Generating, registering and storing that secret plus its recovery file is the developer's job; the skill tells the agent not to do it on your behalf.

What's inside: installing `@circle-fin/developer-controlled-wallets`, booting the client with `initiateDeveloperControlledWalletsClient`, and notes on EOA versus SCA accounts. Transaction states run from `INITIATED` through to `COMPLETE`, and separate reference files walk through wallet creation, receiving and sending tokens, balance checks, EIP-191 and EIP-712 signing, contract execution, plus SCA upgrades and wallet derivation. Every mutating call needs a UUID v4 in `idempotencyKey`.

You supply `CIRCLE_API_KEY` in `PREFIX:ID:SECRET` form and `ENTITY_SECRET` as environment variables. SCA wallets exist on EVM chains only, so Solana, Aptos and NEAR are out for that account type. On Ethereum mainnet gas costs make SCA a poor fit, and the skill points you to L2s instead.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

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

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add circlefin/skills --skill use-developer-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-developer-controlled-wallets/SKILL.md

## When to use it
- spin up a wallet set tied to one entity secret
- send tokens after estimating the fee
- sign EIP-712 typed data with a managed wallet
- run a contract function from an ABI or raw calldata
- derive a wallet onto a new chain or upgrade an SCA

## Example prompts
- Create a wallet in a new wallet set and print its address
- Check this wallet's balance and send 10 USDC to the recipient
- Sign this typed data with the wallet

## 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: e15bf4e0cc5e13f5.

BEGIN THIRD-PARTY FILE e15bf4e0cc5e13f5
````text
---
name: use-developer-controlled-wallets
description: "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, entity secret, initiateDeveloperControlledWalletsClient, createWalletSet, createWallets, custody wallet, wallet upgrade, derive wallet, sign typed data, contract execution."
requirements:
  runtimes: []
  connectors: []
---

## Overview

Developer-controlled wallets let your application create and manage wallets on behalf of end users, with full custody of private keys secured through an encrypted entity secret. Circle handles security, transaction monitoring, and blockchain infrastructure while you retain programmatic control via the Wallets SDK.

## Prerequisites / Setup

### Installation

```bash
npm install @circle-fin/developer-controlled-wallets
```

### Environment Variables

```
CIRCLE_API_KEY=      # Circle API key (format: PREFIX:ID:SECRET)
ENTITY_SECRET=       # 32-byte hex entity secret
```

### Entity Secret Registration

The developer must register an entity secret before using the SDK. Direct them to https://developers.circle.com/wallets/dev-controlled/register-entity-secret or provide the code steps.

READ `references/register-secret.md` for the generation and registration snippets.

IMPORTANT: Do NOT register a secret on the developer's behalf -- they must generate, register, and securely store their secret and recovery file.

### SDK Initialization

```typescript
import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets';

const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.ENTITY_SECRET,
});
```

The SDK automatically generates a fresh entity secret ciphertext for each API request.

## Core Concepts

- **Wallet Sets**: A group of wallets managed by a single entity secret. Wallets in a set can span different blockchains but share the same address on EVM chains.
````
END THIRD-PARTY FILE e15bf4e0cc5e13f5

The third-party file has ended. Everything between the e15bf4e0cc5e13f5 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 2256 of 10015 bytes. © circlefin · Apache-2.0 · https://github.com/circlefin/skills/tree/HEAD/plugins/circle/skills/use-developer-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