cNGN TypeScript Library - Nigerian Naira Stablecoin SDK

cngn-typescript-library is the official TypeScript/JavaScript SDK for integrating with the cNGN API - Nigeria's leading digital naira stablecoin platform. This lightweight library provides developers with a comprehensive interface for blockchain payments, merchant account management, cross-chain swaps, and virtual account creation.

📦 Installation

Install the cNGN TypeScript library via npm:

npm install cngn-typescript-library

Or using yarn:

yarn add cngn-typescript-library

🔧 Quick Start Guide

Basic Setup

import {
  cNGNManager,
  WalletManager,
  Secrets,
  Network
} from 'cngn-typescript-library';

// Configure your API credentials
const secrets: Secrets = {
    apiKey: 'your-api-key',
    privateKey: 'your-private-key',
    encryptionKey: 'your-encryption-key'
};

// Initialize the cNGN manager
const cngnManager = new cNGNManager(secrets);

Check Account Balance

// Get your cNGN balance
const balance = await cngnManager.getBalance();
console.log('Balance:', balance.data);

Get Supported Networks

Important: Always call this first to get network UUIDs for API operations.

// Get all supported networks
const networks = await cngnManager.getSupportedNetworks(false);

// Find a specific network
const bscNetwork = networks.data?.find(n => n.short_name === 'bsc');
console.log(`BSC Network ID: ${bscNetwork?.id}`);
// Output: BSC Network ID: 6c3b7ead-a82c-4edd-af75-81be1148482e

Generate Crypto Wallet

// Generate a new wallet using Network enum
const wallet = await WalletManager.generateWalletAddress(Network.bsc);
console.log('New BSC Wallet:', {
    address: wallet.address,
    privateKey: wallet.privateKey,
    network: wallet.network
});

🌐 Supported Blockchain Networks

The cNGN TypeScript library supports multiple blockchain networks. Network handling differs based on the operation:

Network Enum (for Wallet Generation)

The Network enum is used for wallet generation with WalletManager:

Network	Network Enum
Binance Smart Chain	`Network.bsc`
Ethereum	`Network.eth`
Polygon (Matic)	`Network.matic`
Tron	`Network.trx`
Base	`Network.base`
Solana	`Network.sol`
Asset Chain	`Network.atc`
Bantu Chain	`Network.xbn`
Lisk	`Network.lisk`
Monad	`Network.monad`
Circle Arc chain	`Network.arc`

Network IDs (for API Operations)

For API operations (withdrawals, swaps, whitelisting), you need to use network UUIDs obtained from the getSupportedNetworks() method:

// Get supported networks with their IDs
const networks = await cngnManager.getSupportedNetworks(true);

// Example response
networks.data?.forEach(network => {
    console.log(`${network.name}: ${network.id}`);
    // Output: "Binance Smart Chain: 6c3b7ead-a82c-4edd-af75-81be1148482e"
});

Important:

Use Network enum for WalletManager.generateWalletAddress()
Use network UUID strings (from getSupportedNetworks()) for networkId parameters in API calls

🎯 Core Features

💰 Account Management

Check cNGN balance and transaction history
Real-time balance updates
Multi-currency support

🏦 Banking Integration

Create virtual bank accounts
Instant naira-to-cNGN conversion

🔄 Cross-Chain Operations

Swap cNGN between different blockchains
Bridge assets across networks
Real-time swap quotes and fees

💸 Withdrawals & Redemptions

Withdraw cNGN to any supported blockchain
Redeem cNGN back to Nigerian bank accounts
Verify withdrawal status and references

👛 Wallet Management

Generate HD wallets for any network
Multi-signature wallet support
Secure private key management

📚 API Reference

Complete Workflow Example

import { cNGNManager, Secrets } from 'cngn-typescript-library';

const secrets: Secrets = {
    apiKey: process.env.CNGN_API_KEY!,
    privateKey: process.env.CNGN_PRIVATE_KEY!,
    encryptionKey: process.env.CNGN_ENCRYPTION_KEY!
};

const cngnManager = new cNGNManager(secrets);

async function completeWorkflow() {
    // 1. Get supported networks (always do this first to get network IDs)
    const networks = await cngnManager.getSupportedNetworks(true);
    const bscNetwork = networks.data?.find(n => n.short_name === 'bsc');
    const baseNetwork = networks.data?.find(n => n.short_name === 'base');

    // 2. Check balance
    const balance = await cngnManager.getBalance();
    console.log('Current Balance:', balance.data);

    // 3. Withdraw to blockchain
    const withdrawal = await cngnManager.withdraw({
        amount: 1600,
        address: '0x1767A569Fa8d72527b7a5792F431bF75045AdFc9',
        networkId: bscNetwork!.id,
        shouldSaveAddress: false
    });

    // 4. Verify withdrawal
    const verification = await cngnManager.verifyWithdrawal(withdrawal.data!.trxRef);

    // 5. Cross-chain swap
    const swap = await cngnManager.swapAsset({
        originNetworkId: bscNetwork!.id,
        destinationNetworkId: baseNetwork!.id,
        destinationAddress: '0xfaEcCB96f7C6985E64cfB055221dc512D9fD0845'
    });

    // 6. Redeem to bank account
    const redemption = await cngnManager.redeemAsset({
        amount: 1000000,
        bankCode: '011',
        accountNumber: '3069839406'
    });
}

cNGNManager Methods

Account Operations

// Get account balance
const balance = await cngnManager.getBalance();
console.log('Balance:', balance.data);

// Get transaction history with pagination
const transactions = await cngnManager.getTransactionHistory(1, 20);

console.log('Transactions:', {
    data: transactions.data?.data, // Array of transactions
    pagination: transactions.data?.pagination // Pagination info
});

// Get supported Nigerian banks
const banks = await cngnManager.getBanks();
console.log('Banks:', banks.data?.map(bank => ({
    name: bank.name,
    code: bank.code
})));

Withdrawal Operations

import { IWithdraw } from 'cngn-typescript-library';

// Step 1: Get supported networks to find the network ID
const networks = await cngnManager.getSupportedNetworks(false);
const bscNetwork = networks.data?.find(n => n.short_name === 'bsc');

// Step 2: Withdraw cNGN to blockchain address using network UUID
const withdrawData: IWithdraw = {
    amount: 1600, // Amount in kobo (16 NGN)
    address: '0x1767A569Fa8d72527b7a5792F431bF75045AdFc9',
    networkId: bscNetwork?.id || '6c3b7ead-a82c-4edd-af75-81be1148482e', // Network UUID from API
    shouldSaveAddress: false
};

const withdrawResult = await cngnManager.withdraw(withdrawData);
console.log('Transaction Reference:', withdrawResult.data?.trxRef);

// Verify withdrawal status
const verification = await cngnManager.verifyWithdrawal(withdrawResult.data?.trxRef || 'TNX-REF-12345');
console.log('Withdrawal Status:', verification.data?.status);

Bank Redemption

import { RedeemAsset } from 'cngn-typescript-library';

// Redeem cNGN to Nigerian bank account
const redeemData: RedeemAsset = {
    amount: 1000000, // Amount in kobo (10,000 NGN)
    bankCode: '011', // First Bank code
    accountNumber: '3069839406',
    saveDetails: true // Save bank details for future use
};

const redemption = await cngnManager.redeemAsset(redeemData);

console.log('Redemption Result:', {
    transactionRef: redemption.data?.trx_ref,
    status: redemption.data?.status,
    amount: redemption.data?.amount
});

Virtual Account Management

import { IVirtualAccount } from 'cngn-typescript-library';

// Get existing virtual account details
const virtualAccount = await cngnManager.getVirtualAccount();

console.log('Virtual Account Details:', {
    accountNumber: virtualAccount.data?.accountNumber,
    accountName: virtualAccount.data?.accountName,
    bankName: virtualAccount.data?.bankName,
    bankCode: virtualAccount.data?.bankCode
});

// Use this virtual account to receive Nigerian Naira
// Funds sent to this account are automatically converted to cNGN

Cross-Chain Swaps

import { Swap } from 'cngn-typescript-library';

// Step 1: Get supported networks
const networks = await cngnManager.getSupportedNetworks(false);
const bscNetwork = networks.data?.find(n => n.short_name === 'bsc');
const baseNetwork = networks.data?.find(n => n.short_name === 'base');

// Execute swap
const swapData: Swap = {
    originNetworkId: bscNetwork?.id || '6c3b7ead-a82c-4edd-af75-81be1148482e',
    destinationNetworkId: baseNetwork?.id || '03cae1ad-b62c-41c9-bb9e-2f6321eb947e',
    destinationAddress: '0xfaEcCB96f7C6985E64cfB055221dc512D9fD0845',
    callbackUrl: 'https://yourapp.com/callback', // Optional
    senderAddress: '0x1767A569Fa8d72527b7a5792F431bF75045AdFc9' // Optional
};

const swapResult = await cngnManager.swapAsset(swapData);
console.log('Swap Response:', {
    receivableAddress: swapResult.data?.receivableAddress,
    transactionId: swapResult.data?.transactionId,
    reference: swapResult.data?.reference
});

Network Management

import { SupportedNetworks } from 'cngn-typescript-library';

// Get all supported networks (without blockchain details)
const networks = await cngnManager.getSupportedNetworks(false);

console.log('Supported Networks:');
networks.data?.forEach(network => {
    console.log({
        id: network.id, // UUID to use for networkId in API calls
        name: network.name,
        shortName: network.short_name,
        isDisabled: network.isDisabled
    });
});

// Get supported networks with blockchain details
const networksWithBlockchain = await cngnManager.getSupportedNetworks(true);

console.log('Networks with Blockchain Info:');
networksWithBlockchain.data?.forEach(network => {
    console.log({
        id: network.id,
        name: network.name,
        blockchain: network.blockchain.name
    });
});

Address Whitelisting

import { WhiteListAddress, WalletAccount } from 'cngn-typescript-library';

// Step 1: Get network ID from supported networks
const networks = await cngnManager.getSupportedNetworks(false);
const bscNetwork = networks.data?.find(n => n.short_name === 'bsc');

// Step 2: Whitelist a new address
const whitelistData: WhiteListAddress = {
    address: '0x2DeD9c59cB12bF503dCf089BE13380296590b706',
    networkId: bscNetwork?.id || '9840303d-452b-4e9a-9646-e1141103bf9a' // Network UUID
};

const whitelistResult = await cngnManager.whitelistAddress(whitelistData);
console.log('Whitelisted:', whitelistResult.data);

// Get all whitelisted addresses (without network details)
const whitelistedAddresses = await cngnManager.getWhitelistedAddress(false);

console.log('Whitelisted Addresses:', whitelistedAddresses.data?.map(w => ({
    id: w.id,
    publicKey: w.publicKey,
    networkId: w.networkId
})));

// Get whitelisted addresses with full network information
const whitelistedWithNetwork = await cngnManager.getWhitelistedAddress(true);

console.log('Whitelisted with Network Info:', whitelistedWithNetwork.data?.map(w => ({
    id: w.id,
    publicKey: w.publicKey,
    network: w.network // Full network object included
})));

Bank Account Management

import { BankAccount, VerifyBankAccount } from 'cngn-typescript-library';

// Step 1: Get list of supported banks
const banks = await cngnManager.getBanks();

console.log('Available Banks:', banks.data?.map(bank => ({
    name: bank.name,
    code: bank.code,
    country: bank.country
})));

// Step 2: Verify bank account details before transactions
const verifyData: VerifyBankAccount = {
    bankCode: '011', // First Bank code
    accountNumber: '3069839406'
};

const verification = await cngnManager.verifyBankAccount(verifyData);

console.log('Account Details:', {
    bankName: verification.data?.bank_name,
    accountName: verification.data?.account_name,
    bankCode: verification.data?.bank_code,
    accountNumber: verification.data?.account_number
});

// Step 3: Update/save bank account information
const bankData: BankAccount = {
    bankName: 'First Bank of Nigeria',
    bankAccountName: 'EZUMAH JEREMIAH KALU',
    bankAccountNumber: '3069839406'
};

const updateResult = await cngnManager.updateBankAccount(bankData);
console.log('Bank Account Updated:', updateResult.data);

WalletManager Methods

The WalletManager is used for generating cryptocurrency wallets. It uses the Network enum (not network UUIDs).

import { WalletManager, Network } from 'cngn-typescript-library';

// Generate new wallets using Network enum
const bscWallet = await WalletManager.generateWalletAddress(Network.bsc);
const ethWallet = await WalletManager.generateWalletAddress(Network.eth);
const polygonWallet = await WalletManager.generateWalletAddress(Network.matic);
const solanaWallet = await WalletManager.generateWalletAddress(Network.sol);
const tronWallet = await WalletManager.generateWalletAddress(Network.trx);

console.log('Generated BSC Wallet:', {
    address: bscWallet.address,
    privateKey: bscWallet.privateKey,
    mnemonic: bscWallet.mnemonic,
    network: bscWallet.network // Returns 'bsc'
});

// Alternative: Use string short name directly
const baseWallet = await WalletManager.generateWalletAddress('base');

// ⚠️ Important: These wallets are generated locally
// They are NOT automatically registered with the cNGN API
// Use whitelistAddress() to register them for withdrawals

🧪 Testing

Run the comprehensive test suite:

# Install dependencies
npm install

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Test Coverage

The library maintains >90% test coverage across:

API endpoint integration
Wallet generation functionality
Error handling scenarios
Network compatibility
TypeScript type validation

Example Usage

Check out src/endpoints.ts for comprehensive usage examples of all API methods with real network UUIDs and proper parameter formats.

🔒 Security Features

Encryption & Cryptography

AES Encryption for all API requests
Ed25519 Decryption for secure response handling
BIP39 Mnemonic generation for wallet creation
HD Wallet derivation paths

Best Practices

Never log sensitive credentials
Use environment variables for API keys
Implement proper error handling
Validate all user inputs

// Secure credential management
const secrets: Secrets = {
    apiKey: process.env.CNGN_API_KEY!,
    privateKey: process.env.CNGN_PRIVATE_KEY!,
    encryptionKey: process.env.CNGN_ENCRYPTION_KEY!
};

// Proper error handling
try {
    const result = await manager.getBalance();
} catch (error) {
    if (error.response?.status === 401) {
        console.error('Invalid API credentials');
    } else if (error.response?.status === 429) {
        console.error('Rate limit exceeded');
    } else {
        console.error('Operation failed:', error.message);
    }
}

📝 TypeScript Support

Full TypeScript definitions included:

// All interfaces and types are fully typed
interface Balance {
    asset_type: string;
    asset_code: any;
    balance: string;
}

interface GeneratedWalletAddress {
    mnemonic: string | null;
    address: string;
    network: string;
    privateKey: string;
}

interface IResponse<T> {
    success: boolean;
    data?: T;
    error?: string;
}

// Network enum for type-safe network selection
enum Network {
    bsc = 'bsc',
    atc = 'atc',
    xbn = 'xbn',
    eth = 'eth',
    matic = 'matic',
    trx = 'trx',
    base = 'base',
    lisk = 'lisk',
    monad = 'monad',
    arc = 'arc',
    sol = 'sol'
}

Available Types

Enums

Network - For wallet generation only (bsc, eth, matic, trx, base, sol, atc, xbn, lisk, monad, arc)

// ✅ Correct usage
const wallet = await WalletManager.generateWalletAddress(Network.bsc);

// ❌ Don't use for API operations
// const withdrawal = await cngnManager.withdraw({ networkId: Network.bsc }); // WRONG!

TrxType - Transaction types (fiat_buy, crypto_deposit, enaira_buy, fiat_redeem, withdraw, enaira_redeem, swap)
AssetType - Asset types (fiat, wrapped, enaira)
Status - Transaction status (pending, pending_deposit, failed, rejected, completed)

Important: Network Enum vs Network ID

Network enum = Used for WalletManager.generateWalletAddress()
- Values: Network.bsc, Network.eth, etc.
networkId (UUID string) = Used for all API operations (withdraw, swap, whitelist)
- Values: '6c3b7ead-a82c-4edd-af75-81be1148482e', obtained from getSupportedNetworks()

Core Types

Secrets - API credentials configuration
IResponse<T> - Standard API response wrapper
Balance - Account balance information
Transactions - Transaction history details
ITransactionPagination - Paginated transaction history

Transaction Types

IWithdraw - Withdrawal parameters

interface IWithdraw {
    shouldSaveAddress?: boolean;
    amount: number;
    address: string;
    networkId: string; // UUID from getSupportedNetworks()
}

IWithdrawResponse - Withdrawal response with transaction reference
RedeemAsset - Bank redemption data

Virtual Account & Banking

IVirtualAccount - Virtual account details
BankAccount - Bank account information
VerifyBankAccount - Bank account verification parameters
VerifyBankAccountResponse - Bank account verification result
IBanks - Supported banks list

Swap & Cross-Chain

Swap - Cross-chain swap parameters

interface Swap {
    destinationNetworkId: string; // UUID from getSupportedNetworks()
    destinationAddress: string;
    originNetworkId: string; // UUID from getSupportedNetworks()
    callbackUrl?: string;
    senderAddress?: string;
}

SwapResponse - Swap transaction response

ISwapQuote - Swap quote parameters

interface ISwapQuote {
    amount: number;
    destinationAddress: string;
    originNetworkId: string; // UUID from getSupportedNetworks()
    destinationNetworkId: string; // UUID from getSupportedNetworks()
}

ISwapQuoteResponse - Swap quote with fees

Network & Address Management

SupportedNetworks - List of supported blockchain networks
WalletAccount - Whitelisted wallet account
WhiteListAddress - Address whitelisting parameters

Wallet Generation

GeneratedWalletAddress - Wallet generation response

Deprecated

UpdateExternalAccount - ⚠️ Deprecated: Use whitelistAddress() and updateBankAccount() instead

🚀 Production Usage

Environment Configuration

# .env file
CNGN_API_KEY=your_production_api_key
CNGN_PRIVATE_KEY=your_production_private_key
CNGN_ENCRYPTION_KEY=your_production_encryption_key

Development Setup

git clone https://github.com/your-username/cngn-typescript-library.git
cd cngn-typescript-library
npm install
npm run build
npm test

📞 Support & Community

GitHub Issues: Report bugs and request features
Documentation: Full API documentation
Email Support: support@withconvexity.com
Website: https://cngn.co

Getting Help

Check the documentation
Search existing issues
Create a new issue with detailed information

📄 License

This project is licensed under the ISC License.

🏷️ Keywords

cNGN, Nigerian Naira, Stablecoin, TypeScript, JavaScript, Blockchain, Crypto, Fintech, Nigeria, Digital Payments, API SDK, Ethereum, Binance Smart Chain, Polygon, Tron, Cross-chain, Virtual Accounts, Banking Integration, Merchant API, CBDC

Made with ❤️ by Convexity for the Nigerian fintech ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
src		src
.gitignore		.gitignore
README.md		README.md
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

cNGN TypeScript Library - Nigerian Naira Stablecoin SDK

📋 Table of Contents

📦 Installation

🔧 Quick Start Guide

Basic Setup

Check Account Balance

Get Supported Networks

Generate Crypto Wallet

🌐 Supported Blockchain Networks

Network Enum (for Wallet Generation)

Network IDs (for API Operations)

🎯 Core Features

💰 Account Management

🏦 Banking Integration

🔄 Cross-Chain Operations

💸 Withdrawals & Redemptions

👛 Wallet Management

📚 API Reference

Complete Workflow Example

cNGNManager Methods

Account Operations

Withdrawal Operations

Bank Redemption

Virtual Account Management

Cross-Chain Swaps

Network Management

Address Whitelisting

Bank Account Management

WalletManager Methods

🧪 Testing

Test Coverage

Example Usage

🔒 Security Features

Encryption & Cryptography

Best Practices

📝 TypeScript Support

Available Types

Enums

Important: Network Enum vs Network ID

Core Types

Transaction Types

Virtual Account & Banking

Swap & Cross-Chain

Network & Address Management

Wallet Generation

Deprecated

🚀 Production Usage

Environment Configuration

Development Setup

📞 Support & Community

Getting Help

📄 License

🏷️ Keywords

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages