CEX Wallets Guide

This guide provides comprehensive information about Centralized Exchange (CEX) wallets, their setup, management, and maintenance procedures.

What are CEX Wallets?

CEX wallets are accounts that depend on centralized exchanges such as:

• KuCoin
• HTX
• Binance

These wallets are essential for managing cryptocurrency operations through centralized exchanges. Each CEX wallet can be either a main wallet or a sub-wallet, and can serve different purposes like vault operations or deposits.

Wallet Structure

Types of Wallets

1. Main Wallets

   • Primary wallets for each exchange
   • Used for core exchange operations
   • Required for updating coin and blockchain information
   • Used as the primary connection point for exchange API operations

2. Sub Wallets

   • Secondary wallets that can be linked to main wallets
   • Can be used for specific purposes like vault operations
   • May have different permissions and capabilities
   • Often used for specific business functions like vault partnerships

Wallet Properties

Each CEX wallet contains:

• Unique ID (combination of exchange and origin wallet ID)
• Exchange type (KuCoin, HTX, Binance)
• Wallet type (main or sub)
• Encrypted API credentials (API key and secret)
• Wallet purpose (vault, deposit, etc.)
• Vault partner information (if applicable)
• Associated email
• Active status

Wallet Management

Initial Setup

1. Create CEX wallets using the Deposit functionality
2. Run the VanRan Deposit within the Database folder
3. This sets up the basic wallet structure for each exchange

Managing Exchange Coins and Blockchains

In the admin interface, under CexWalletCoins, you can perform the following operations:

1. Update available coins for each exchange
2. This process brings all supported coins with their respective blockchains for each exchange
3. Examples of supported combinations:
   • AAVE on Ethereum
   • AAVE on BSC
   • USDT on Tron
   • USDT on BSC
   • USDT on Ethereum

The system uses the CexCoinsBlockchainsUpdater service to:

• Fetch all available coins from the system
• Retrieve network information from the exchange
• Create and save CexCoinBlockchain entities for each supported combination

Coin Status Management

Under CexWalletCoinsCurrentStatuses, you can:

1. Update the status of each coin for every exchange and blockchain
2. View and manage:
   • Withdrawal availability
   • Deposit availability
   • Transaction fees
   • Minimum withdrawal amounts
   • Deposit limits

The system uses the CexCoinBlockchainStatusUpdater service to:

• Fetch existing coin-blockchain combinations
• Retrieve network status information from the exchange
• Update or create CexCoinBlockchainStatus entities with current fees and limits

Wallet Balance Management

Each wallet has associated coin wallets that:

1. Track balances for different coins
2. Aggregate balances across different blockchains
3. Example: If you have 5 USDT on Tron and 5 USDT on BSC, the total balance will show as 10 USDT

The system uses the CexAccountCoinWalletsUpdater service to:

• Fetch current balances from the exchange
• Create or update CexAccountCoinWallet entities
• Track both available and locked balances for each coin

Deposit Addresses

1. Access through CexWalletAccountsDepositAddresses
2. Use the Update function to:
   • View deposit addresses for each coin-blockchain combination
   • Manage deposit address configurations

The system uses the CexAccountCoinBlockchainAddressUpdater service to:

• Identify active coin-blockchain combinations with deposit enabled
• Fetch deposit addresses from the exchange
• Create and save CexAccountCoinBlockchainAddress entities
• Handle rate limiting by processing addresses sequentially

Local Development Setup

For local development, you can use the database seeding feature to create basic CEX wallets automatically.

Prerequisites

• Access to the project's database package
• Local environment variables configured properly
• SECRETS_KEY for decrypting the API keys (request this from the dev leader)

Steps to Set Up Local CEX Wallets

1. Navigate to the database package directory:

cd /path/to/database-package

2. Make sure your environment has the correct SECRETS_KEY variable set:

export SECRETS_KEY="your-secret-key" # Request the actual key from dev leader

3. Run the database seed with the CEX wallets flag enabled:

bun run db:seed

Security Considerations

• API keys are encrypted using the SECRETS_KEY
• Different wallet types have different permission levels
• Main wallets are required for certain operations
• API keys should never be stored in plain text
• Each wallet's purpose and vault partner information is tracked for security
• The system uses value objects and domain entities to ensure data integrity

Troubleshooting

If you encounter issues with the CEX wallets:

• Verify you have the correct SECRETS_KEY
• Check database connection settings
• Ensure the seeding process completed successfully
• Review logs for any errors during the seeding process
• Verify that all update processes (coins, statuses, wallets, deposit addresses) completed successfully
• Check if the main wallet exists for the exchange you're working with
• Verify API key permissions and encryption
• Check for rate limiting issues when fetching deposit addresses
• Ensure the exchange API is accessible and responding correctly

For additional assistance, contact the development team lead.