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:

``bash
npm install cngn-typescript-library
`

Or using yarn:

`bash
yarn add cngn-typescript-library
`

🔧 Quick Start Guide

$3

`typescript
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);
`

$3

`typescript
// Get your cNGN balance
const balance = await cngnManager.getBalance();
console.log(Current balance: ${balance.amount} cNGN);
`

$3

`typescript
// Generate a new wallet address for any supported network
const wallet = await WalletManager.generateWalletAddress(Network.bsc);
console.log(New BSC address: ${wallet.address});
`

🌐 Supported Blockchain Networks

The cNGN TypeScript library supports all major blockchain networks:

| Network | Code | Description |
|---------|------|-------------|
| Binance Smart Chain | Network.bsc | Low-cost, fast transactions |
| Ethereum | Network.eth | Most secure, highest liquidity |
| Polygon (Matic) | Network.matic | Ethereum-compatible, low fees |
| Tron | Network.trx | High throughput blockchain |
| Base | Network.base | Coinbase's L2 solution |
| Asset Chain | Network.atc | African-focused blockchain |
| Bantu Chain | Network.xbn | African blockchain network |

📋 Table of Contents

- Installation
- Quick Start
- Supported Networks
- API Reference
- Testing
- Security
- TypeScript Support
- Contributing
- Support

🎯 Core Features

$3

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

$3

- Create virtual bank accounts (Korapay)
- Instant naira-to-cNGN conversion

$3

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

$3

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

$3

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

📚 API Reference

$3

#### Account Operations

`typescript
// Get account balance
const balance = await cngnManager.getBalance();

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

// Get supported Nigerian banks
const banks = await cngnManager.getBanks();
`

#### Withdrawal Operations

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

// Withdraw cNGN to blockchain address
const withdrawData: IWithdraw = {
amount: 50000, // Amount in kobo (500 NGN)
address: 'ENTER_ADDRESS',
network: Network.bsc,
shouldSaveAddress: true
};

const withdrawResult = await cngnManager.withdraw(withdrawData);

// Verify withdrawal status
const verification = await cngnManager.verifyWithdrawal('TNX-REF-12345');
`

#### Bank Redemption

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

// Redeem cNGN to Nigerian bank account
const redeemData: RedeemAsset = {
amount: 100000, // Amount in kobo (1,000 NGN)
bankCode: '058', // GTBank code
accountNumber: 'ENTER_ACCOUNT_NUMBER',
saveDetails: true
};

const redemption = await cngnManager.redeemAsset(redeemData);
`

#### Virtual Account Creation

`typescript
import { CreateVirtualAccount } from 'cngn-typescript-library';

// Create virtual account for receiving naira
const virtualAccountData: CreateVirtualAccount = {
provider: 'korapay',
bank_code: '058' // GTBank
};

const virtualAccount = await cngnManager.createVirtualAccount(virtualAccountData);
`

#### Cross-Chain Swaps

`typescript
import { Swap, ISwapQuote } from 'cngn-typescript-library';

// Get swap quote
const quoteData: ISwapQuote = {
destinationNetwork: Network.eth,
destinationAddress: 'ENTER_DESTINATION_ADDRESS',
originNetwork: Network.bsc,
amount: 50000
};

const quote = await cngnManager.getSwapQuote(quoteData);

// Execute swap
const swapData: Swap = {
destinationNetwork: Network.eth,
destinationAddress: 'ENTER_DESTINATION_ADDRESS',
originNetwork: Network.bsc,
callbackUrl: 'https://yourapp.com/callback', // Optional
senderAddress: "ENTER_SENDER_ADDRESS" //optional
};

const swapResult = await cngnManager.swapAsset(swapData);
`

$3

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

// Generate new wallet for any network
const bscWallet = await WalletManager.generateWalletAddress(Network.bsc);
const ethWallet = await WalletManager.generateWalletAddress(Network.eth);
const polygonWallet = await WalletManager.generateWalletAddress(Network.matic);

console.log('BSC Wallet:', {
address: bscWallet.address,
privateKey: bscWallet.privateKey,
mnemonic: bscWallet.mnemonic
});
`

🧪 Testing

Run the comprehensive test suite:

`bash

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
`

$3

The library maintains >90% test coverage across:
- API endpoint integration
- Wallet generation functionality
- Error handling scenarios
- Network compatibility
- TypeScript type validation

🔒 Security Features

$3

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

$3

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

`typescript
// 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:

`typescript
// 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: Network;
privateKey: string;
}

interface IResponse {
success: boolean;
data: T;
message?: string;
errors?: string[];
}
`

$3

- Secrets - API credentials configuration
- IResponse - Standard API response wrapper
- Balance - Account balance information
- Transactions - Transaction history details
- IWithdraw - Withdrawal parameters
- RedeemAsset - Bank redemption data
- CreateVirtualAccount - Virtual account creation
- UpdateExternalAccount - Business account updates
- Swap - Cross-chain swap parameters
- GeneratedWalletAddress - Wallet generation response

🚀 Production Usage

$3

`bash

.env file

CNGN_API_KEY=your_production_api_key
CNGN_PRIVATE_KEY=your_production_private_key
CNGN_ENCRYPTION_KEY=your_production_encryption_key
`

$3

`bash
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

$3

1. Check the documentation
2. Search existing issues
3. 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