KuCoin Exchange Integration

Relevant source files

The following files were used as context for generating this wiki page:

• core/integrations.py
• core/commands.py
• core/bot.py
• core/database.py
• requirements.txt
• tests/test_commands.py

The KuCoin Exchange Integration module provides the GentelmeN-CorE system with real-time cryptocurrency market data, portfolio management capabilities, and a persistent price alerting system. It leverages the ccxt library to interface with the KuCoin API, allowing users to query asset prices, monitor balances, and receive automated notifications when specific market conditions are met.

Sources: core/bot.py:27-35, requirements.txt:4

Architecture and Components

The integration is built upon three main functional pillars: interactive commands for manual queries, a background monitoring thread for automated alerts, and a PostgreSQL backend for persisting user-defined price triggers.

Initialization and Configuration

The system initializes the KuCoin client using environment variables for authentication. If the required credentials are missing or incorrect, the client is set to None, and dependent features are gracefully disabled with an error message to the user.

Environment Variable	Description
KUCOIN_API_KEY	Public API key for KuCoin access
KUCOIN_SECRET	Secret key for request signing
KUCOIN_PASSWORD	API passphrase required by KuCoin

Sources: core/bot.py:16-35, core/commands.py:25-28

Component Relationship

The following diagram illustrates how the KuCoin integration interacts with the Telegram bot interface and the database.

The interaction involves a request-response cycle for manual commands and a continuous polling loop for the price monitor.
Sources: core/bot.py:38-41, core/commands.py:186-189

Functional Features

Market Data and Balance

Users can interact with the exchange through specific commands defined in core/commands.py.

• Price Check (/cena): Fetches the last traded price for a specific trading pair (e.g., BTC/USDT).
• Balance Check (/balance): Retrieves the total account balance. This command is restricted to the administrator (defined by OWNER_USER_ID or a specific username) and filters out assets with zero balances.

Sources: core/commands.py:30-47, core/commands.py:100-136

Price Alerting System

The alerting system allows users to set target prices for specific symbols. Alerts are categorized by direction: UP (if the target is above the current price) or DOWN (if below).

The sequence demonstrates the logic used to determine the trigger direction before persisting the alert to the database.
Sources: core/commands.py:50-80, core/database.py:28-36

Price Monitor Thread

A dedicated background thread, price_monitor, runs every 60 seconds to evaluate active alerts.

1. Fetch Alerts: Retrieves all active alerts from the alerts table.
2. Batch Processing: Aggregates unique symbols to minimize API calls via kucoin.fetch_tickers.
3. Comparison Logic: Compares current market prices against target_price based on the saved direction.
4. Notification and Cleanup: If a target is hit, it sends a Telegram message to the user and deletes the alert from the database to prevent duplicate notifications.

# Comparison logic in core/bot.py
hit = (
    (direction == 'UP' and curr_price >= target)
    or (direction == 'DOWN' and curr_price <= target)
)

Sources: core/bot.py:38-76

Data Schema

The integration relies on the alerts table within the PostgreSQL database for persistence.

Field	Type	Description
id	SERIAL	Primary key
user_id	BIGINT	Telegram ID of the alert owner
symbol	TEXT	Market pair (e.g., ETH/USDT)
target_price	NUMERIC	The price threshold to trigger the alert
direction	TEXT	Either 'UP' or 'DOWN'

Sources: core/database.py:28-36

Error Handling

The integration implements robust error handling to prevent bot crashes:

• API Failures: Wrapped in try-except blocks to catch network issues or invalid symbols during fetch_ticker.
• Initialization: If KuCoin fails to initialize in core/bot.py, the _kucoin variable is set to None, and commands check this state before attempting execution.
• Database Connectivity: Alerts are handled within connection contexts to ensure proper closure even on failure.

Sources: core/bot.py:32-35, core/commands.py:31-33, tests/test_commands.py:245-310

This integration ensures the GeNCorE bot serves as a functional tool for cryptocurrency traders by combining manual utility commands with automated monitoring.