@venturialstd/circle

A comprehensive NestJS module for integrating with Circle's User-Controlled Wallets and Developer-Controlled Wallets APIs.

Features

• Wallet Management: Create and manage wallets across multiple blockchains
• Wallet Sets: Organize wallets into sets for better management
• Transaction Management: Create and track transactions on various blockchains
• Token Balance Tracking: Monitor token balances for wallets
• NFT Balance Tracking: Track NFT balances for wallets
• Challenge Management: Handle user challenges for wallet operations
• API Operation Logging: Comprehensive logging of all Circle API operations
• Real-time Settings: Dynamic configuration via SettingsService

Installation

npm install @venturialstd/circle

Usage

Import the Module

import { Module } from '@nestjs/common';
import { CircleModule } from '@venturialstd/circle';

@Module({
  imports: [CircleModule],
})
export class AppModule {}

Configure Settings

Before using the module, configure Circle API settings through the Settings module:

• GLOBAL:CIRCLE:GENERAL:API_KEY - Your Circle API key (required)
• GLOBAL:CIRCLE:GENERAL:ENTITY_SECRET - Entity secret for developer-controlled wallets (optional)
• GLOBAL:CIRCLE:GENERAL:BASE_URL - Circle API base URL (optional, defaults to https://api.circle.com)

Use the Services

import { Injectable } from '@nestjs/common';
import {
  CircleWalletService,
  CircleTransactionService,
} from '@venturialstd/circle';

@Injectable()
export class WalletService {
  constructor(
    private readonly circleWalletService: CircleWalletService,
    private readonly circleTransactionService: CircleTransactionService,
  ) {}

  async createWallet(blockchains: string[], walletSetId: string) {
    return this.circleWalletService.createWallets(blockchains, walletSetId);
  }

  async createTransaction(walletId: string, amounts: string[], destinationAddress: string) {
    return this.circleTransactionService.createTransaction(
      walletId,
      amounts,
      destinationAddress,
    );
  }
}

Testing

The module includes a comprehensive test application that you can run locally.

Setup

1. Copy the example environment file:

cd test
cp env.template .env

2. Update the .env file with your database credentials.

3. Create the database:

createdb circle_test

4. Run migrations:

npm run migration:run

5. Start the test server:

npm run test:dev

The test server will start on http://localhost:3004 with all endpoints available for testing.

Available Scripts

• npm run build - Build the module
• npm run test:dev - Start the test server
• npm run test:watch - Start the test server with auto-reload
• npm run migration:generate --name=MigrationName - Generate a new migration
• npm run migration:run - Run pending migrations
• npm run migration:revert - Revert the last migration

Entities

CircleWallet

Represents a wallet created via Circle API.

CircleWalletSet

Represents a set of wallets for organization.

CircleTransaction

Represents a transaction on a blockchain.

CircleTokenBalance

Represents token balances for a wallet.

CircleNFTBalance

Represents NFT balances for a wallet.

CircleChallenge

Represents user challenges for wallet operations.

CircleApiOperation

Logs all Circle API operations for debugging and auditing.

Services

All services extend TypeOrmCrudService from @dataui/crud-typeorm for consistent CRUD operations.

CircleWalletService

• createWallets() - Create wallets via Circle API
• listWallets() - List wallets from Circle API
• getWallet() - Get a wallet from Circle API

CircleTransactionService

• createTransaction() - Create a transaction via Circle API
• listTransactions() - List transactions from Circle API
• getTransaction() - Get a transaction from Circle API

CircleTokenBalanceService

• getWalletTokenBalance() - Get token balances for a wallet

CircleNFTBalanceService

• getWalletNFTBalance() - Get NFT balances for a wallet

CircleChallengeService

• listChallenges() - List challenges for a user

CircleApiService

• makeApiCall() - Make API calls to Circle with automatic logging
• getApiKey() - Get API key from settings
• getBaseUrl() - Get base URL from settings

License

MIT

Support

For issues and questions, please open an issue on the repository.