Circle Wallets Adapter

🔐 Enterprise-grade hybrid adapter for EVM and Solana powered by Circle Wallets

Seamlessly manage cross-chain operations with developer-controlled wallets

⚠️ SERVER-SIDE ONLY - Requires API keys and entity secrets that must never be exposed to browsers

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.

Why Circle Wallets Adapter?

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

When and How Should I Use The Circle Wallets Adapter?

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:

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

⚠️ Server-Side Only

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

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

Initial Setup - Generate and Register Entity Secret (If Not Already Done)

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:

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_<timestamp>.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:

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

🚀 Basic Setup

Create an adapter instance with your Circle credentials:

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

Cross-Chain Bridging with Bridge Kit

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

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

Direct SDK Access

Access the underlying Circle Wallets SDK for advanced operations:

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

Factory Function

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

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

Adapter Methods

getSdk()

Returns the underlying Circle Wallets SDK clients for advanced operations.

Returns: Promise<CircleWalletsSDK>

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.

Ready to integrate?

Join Discord • Visit our Help-Desk • Circle Developer Docs

Built with ❤️ by Circle