@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

``bash
npm install @venturialstd/circle
`

Usage

$3

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

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

$3

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)

$3

`typescript
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.

$3

1. Copy the example environment file:
`bash
cd test
cp env.template .env
`

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

3. Create the database:
`bash
createdb circle_test
`

4. Run migrations:
`bash
npm run migration:run
`

5. Start the test server:
`bash
npm run test:dev
`

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

$3

- 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

$3

Represents a wallet created via Circle API.

$3

Represents a set of wallets for organization.

$3

Represents a transaction on a blockchain.

$3

Represents token balances for a wallet.

$3

Represents NFT balances for a wallet.

$3

Represents user challenges for wallet operations.

$3

Logs all Circle API operations for debugging and auditing.

Services

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

$3


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

$3

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

$3

- getWalletTokenBalance() - Get token balances for a wallet

$3

- getWalletNFTBalance() - Get NFT balances for a wallet

$3

- listChallenges() - List challenges for a user

$3

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