Circle Wallets Adapter

Table of Contents

- Circle Wallets Adapter
- Table of Contents
- Overview
- Why Circle Wallets Adapter?
- When and How Should I Use The Circle Wallets Adapter?
- I'm a developer building a backend service
- I'm a developer making a Kit Provider
- ⚠️ Server-Side Only
- Installation
- Initial Setup - Generate and Register Entity Secret (If Not Already Done)
- Quick Start
- 🚀 Basic Setup
- Usage Examples
- Cross-Chain Bridging with Bridge Kit
- Direct SDK Access
- API Reference
- Factory Function
- Adapter Methods
- Supported Chains
- License

Overview

The Circle Wallets Adapter is a hybrid adapter that provides unified access to both EVM and Solana blockchains through Circle's developer-controlled wallet infrastructure. Unlike ecosystem-specific adapters (Viem, Ethers, Solana), this adapter seamlessly operates across both ecosystems using a single instance.

Built for enterprise and backend applications, this adapter integrates Circle Wallets and Circle Contracts to provide secure, programmatic wallet management.

$3

- 🌉 True Cross-Ecosystem Support - Single adapter instance works across EVM chains (Ethereum, Base, Polygon, etc.) AND Solana
- 🏢 Enterprise-Grade - Built on Circle's institutional wallet infrastructure with developer-controlled addressing
- 🔐 Secure by Design - API key and entity secret authentication keeps credentials server-side only
- 🔒 Type-Safe - Built with TypeScript strict mode for complete type safety
- 🎯 Simplified Management - One adapter for all chains eliminates the need to manage separate EVM and Solana adapters
- 🔄 Complete Transaction Lifecycle - Full prepare/estimate/execute workflow across both ecosystems
- 🚀 Production Ready - Leverage Circle's reliable infrastructure and built-in wallet management

$3

#### I'm a developer building a backend service

If you're building a server-side application that needs to perform blockchain operations across EVM and Solana using Circle Wallets, this adapter provides a unified interface for both ecosystems.

Perfect for:

- Backend services performing automated cross-chain transfers
- Enterprise applications managing wallets programmatically
- Server-side scripts requiring multi-ecosystem support
- Applications using Circle's custody infrastructure

Example:

``typescript
import { createCircleWalletsAdapter } from '@circle-fin/adapter-circle-wallets'

// Server-side only - credentials from secure environment variables
const adapter = createCircleWalletsAdapter({
apiKey: process.env.CIRCLE_API_KEY!,
entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
})

// Same adapter works for both EVM and Solana operations!
`

#### I'm a developer making a Kit Provider

If you're building a provider (e.g., a custom BridgingProvider) that needs to work across both EVM and Solana, the Circle Wallets Adapter provides a unified abstraction. You don't need separate adapters for each ecosystem.

Benefits:

- Single adapter instance for cross-ecosystem operations
- Consistent API across EVM and Solana chains
- Built-in wallet management through Circle's infrastructure
- Developer-controlled addressing for explicit wallet specification

$3

This adapter can ONLY be used in server-side (Node.js) environments and will fail in browsers.

Security Reasons:

- ❌ API Keys - Your Circle API key must never be exposed to client-side code
- ❌ Entity Secrets - Entity secrets are sensitive credentials that must remain server-side only
- ❌ Wallet Control - Developer-controlled wallets should only be accessible from trusted backend services

Technical Reasons:

- ❌ Node.js Dependencies - Requires Node.js built-in modules (crypto, buffer, etc.) not available in browsers
- ❌ SDK Requirements - Circle's Developer Controlled Wallets SDK requires a Node.js runtime environment

✅ For Browser Applications:
Use browser-compatible adapters instead:

- @circle-fin/adapter-viem-v2 - For EVM chains with browser wallets
- @circle-fin/adapter-solana - For Solana with browser wallets
- @circle-fin/adapter-ethers-v6 - For EVM chains with Ethers.js

Installation

`bash
npm install @circle-fin/adapter-circle-wallets


or


yarn add @circle-fin/adapter-circle-wallets
`

Prerequisites:

- Node.js environment (v18+ recommended)
- Circle API Key and Entity Secret from Circle Developer Console

$3

If you haven't already set up an entity secret with Circle, you'll need to complete a one-time setup process. The adapter provides convenience utilities (re-exported from Circle's SDK) to simplify this:

`typescript
import {
generateEntitySecret,
registerEntitySecretCiphertext,
} from '@circle-fin/adapter-circle-wallets/utils'

// Step 1: Generate a new entity secret
const entitySecret = generateEntitySecret()
console.log('Generated entity secret:', entitySecret)

// Step 2: Register the entity secret with Circle
const response = await registerEntitySecretCiphertext({
apiKey: 'TEST_API_KEY:abc123:def456', // Your Circle API key
entitySecret: entitySecret,
})

console.log('Recovery file:', response.data?.recoveryFile)
// The recovery file is also automatically downloaded to your filesystem
`

Important Security Notes:

- ⚠️ Entity Secret - Store this securely in environment variables. Never commit it to version control.
- ⚠️ Recovery File - Back up the generated recovery_file_.dat securely. This is your only way to restore access if the entity secret is lost.
- ⚠️ One-Time Setup - This only needs to be done once per Circle account/environment (test/production). If you already have an entity secret registered, skip this step.

After completing this setup (or if you already have credentials), store your entity secret in environment variables:

`bash


.env file (add to .gitignore!)


CIRCLE_API_KEY=TEST_API_KEY:abc123:def456
CIRCLE_ENTITY_SECRET=your-generated-64-char-secret
`

> Note: These utilities are re-exported from @circle-fin/developer-controlled-wallets for convenience. For more details, see the Circle Developer Controlled Wallets documentation.

Quick Start

$3

Create an adapter instance with your Circle credentials:

`typescript
import { createCircleWalletsAdapter } from '@circle-fin/adapter-circle-wallets'

// Initialize adapter with Circle credentials (server-side only!)
const adapter = createCircleWalletsAdapter({
apiKey: process.env.CIRCLE_API_KEY!, // Format: TEST_API_KEY:abc:def or Base64
entitySecret: process.env.CIRCLE_ENTITY_SECRET!, // Format: 64 lowercase alphanumeric chars
})

// Works across both EVM and Solana!
// No need to create separate adapters for each ecosystem
`

API Key Format:

- Environment-prefixed: TEST_API_KEY:abc123:def456 or LIVE_API_KEY:xyz:uvw
- Base64 encoded: Standard Base64 string

Entity Secret Format:

- 64 lowercase alphanumeric characters (e.g., abc123... × 64 chars)

Usage Examples

$3

Use the Circle Wallets Adapter with Bridge Kit for seamless cross-chain USDC transfers across both EVM and Solana:

`typescript
import { createCircleWalletsAdapter } from '@circle-fin/adapter-circle-wallets'
import { BridgeKit } from '@circle-fin/bridge-kit'

// Single adapter instance for both ecosystems
const adapter = createCircleWalletsAdapter({
apiKey: process.env.CIRCLE_API_KEY!,
entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
})

const kit = new BridgeKit()

// Bridge from Ethereum (EVM) to Solana - same adapter for both!
const result = await kit.bridge({
from: {
adapter,
chain: 'Ethereum',
address: '0x1234...', // EVM address (developer-controlled)
},
to: {
adapter, // Same adapter instance!
chain: 'Solana',
address: 'ABC123...', // Solana address (developer-controlled)
},
amount: '100.00',
token: 'USDC',
})

console.log('Bridge transaction:', result.transactionHash)
`

Key Benefits:

- ✅ One adapter for cross-ecosystem bridging (EVM ↔ Solana)
- ✅ Developer-controlled addressing for explicit wallet specification
- ✅ Unified API regardless of source/destination chain type

$3

Access the underlying Circle Wallets SDK for advanced operations:

`typescript
import { createCircleWalletsAdapter } from '@circle-fin/adapter-circle-wallets'

const adapter = createCircleWalletsAdapter({
apiKey: process.env.CIRCLE_API_KEY!,
entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
})

// Access Circle's Developer Controlled Wallets and Smart Contract Platform clients
const sdk = await adapter.getSdk()

// Use Developer Controlled Wallets client
const wallets = await sdk.devc.listWallets()
console.log('Available wallets:', wallets)

// Use Smart Contract Platform client
const contracts = await sdk.scp.listContracts()
console.log('Deployed contracts:', contracts)
`

API Reference

$3

#### createCircleWalletsAdapter(options)

Creates a Circle Wallets adapter instance for server-side use.

Parameters:

- apiKey - Circle API key (environment-prefixed or Base64 format)
- entitySecret - Circle entity secret (64 lowercase alphanumeric characters)
- baseUrl? - Optional custom Circle API base URL (default: Circle's production endpoint)

Returns: CircleWalletsAdapter instance

Throws: Validation error if API key or entity secret format is invalid

`typescript
const adapter = createCircleWalletsAdapter({
apiKey: process.env.CIRCLE_API_KEY!,
entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
baseUrl: 'https://api.circle.com/v1', // Optional
})
`

$3

#### getSdk()

Returns the underlying Circle Wallets SDK clients for advanced operations.

Returns: Promise

`typescript
const sdk = await adapter.getSdk()

// Access Developer Controlled Wallets client
sdk.devc.listWallets()

// Access Smart Contract Platform client
sdk.scp.listContracts()
`

#### Inherited Methods

The Circle Wallets Adapter extends HybridAdapter and supports all standard adapter methods:

- prepare(params, ctx) - Prepare contract transactions
- signTypedData(typedData, ctx) - Sign EIP-712 typed data (EVM) or messages (Solana)
- getAddress(ctx) - Get wallet address for specified chain
- validateChainSupport(chain) - Validate chain compatibility

All methods support the developer-controlled addressing pattern - you must specify the address in the operation context.

Supported Chains

The Circle Wallets Adapter supports a curated subset of CCTP v2-enabled chains across both EVM and Solana ecosystems:

Mainnet (9 chains):

- Arbitrum
- Avalanche
- Base
- Ethereum
- Monad
- OP Mainnet
- Polygon PoS
- Solana
- Unichain

Testnet (9 chains):

- Arc Testnet
- Arbitrum Sepolia
- Avalanche Fuji
- Base Sepolia
- Ethereum Sepolia
- Monad Testnet
- OP Sepolia
- Polygon PoS Amoy
- Solana Devnet
- Unichain Sepolia

> Note: Circle Wallets supports a subset of all CCTP v2 chains. For full CCTP v2 chain support with external wallets, use @circle-fin/adapter-viem-v2 (34 EVM chains) or @circle-fin/adapter-solana-kit` for Solana.

License

This project is licensed under the Apache 2.0 License. Contact support for details.

---