Crypto Portfolio Management

Relevant source files

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

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

The Crypto Portfolio Management system within GentelmeN-CorE provides a robust interface for users to interact with cryptocurrency markets directly via Telegram. The system integrates with the KuCoin exchange via the ccxt library to provide real-time price data, balance inquiries, and automated price alerts.

The scope of this module includes fetching current ticker prices, managing user-defined price alerts stored in a PostgreSQL database, and retrieving account balances for authorized users. It operates through a combination of synchronous command handlers and an asynchronous background monitoring thread.

Sources: core/commands.py:27-133, core/bot.py:28-72, requirements.txt:4

System Architecture

The architecture relies on three primary pillars: the Telegram Bot API for user interaction, the KuCoin API for market data, and a PostgreSQL database for persistent storage of alerts and user preferences.

Data Flow Overview

The following diagram illustrates how user requests for price data and alerts are processed through the system components.

Core Components

1. Market Data Integration

The system utilizes the ccxt library to interface with KuCoin. Authentication is handled via environment variables including KUCOIN_API_KEY, KUCOIN_SECRET, and KUCOIN_PASSWORD. If these variables are missing or incorrect, the system defaults the _kucoin object to None, effectively disabling crypto features.

Sources: core/bot.py:28-36, core/commands.py:27-30

2. Price Alert System

The price alert system allows users to set thresholds for specific trading pairs (e.g., BTC/USDT). Alerts are stored in the alerts table and monitored by a dedicated background thread.

Database Schema (Alerts)

The alerts table is initialized during the database setup process.

Field	Type	Description
id	SERIAL	Primary key for the alert record.
user_id	BIGINT	The Telegram ID of the user who set the alert.
symbol	TEXT	The trading pair symbol (e.g., "ETH/USDT").
target_price	NUMERIC	The price at which the alert should trigger.
direction	TEXT	Direction of price movement: 'UP' or 'DOWN'.

Sources: core/database.py:25-31, core/commands.py:59-62

Monitoring Logic

The price_monitor function runs in a daemon thread, waking every 60 seconds to check active alerts against current market prices.

Command Reference

The crypto module is exposed via several Telegram commands registered in the bot's central command registry.

Price Inquiries

The /cena [symbol] command retrieves the latest ticker information.

• Logic: It splits the user input to extract the symbol, calls fetch_ticker(symbol) via the KuCoin client, and returns the last price.
• Error Handling: If the symbol is invalid or the API is offline, it returns a formatted error message using inteligentna_odpowiedz.

Sources: core/commands.py:32-47, tests/test_commands.py:19-45

Alert Management

Users manage alerts through two primary commands:

• /alert [symbol] [target]: Persists a new alert. It automatically determines the direction ('UP' or 'DOWN') by comparing the target to the current price.
• /alerty: Displays a list of all active alerts for the requesting user, including the ID, symbol, and target price.

Sources: core/commands.py:50-101

Balance and Security

The /balance command provides a summary of the user's KuCoin assets.

• Security: Access is restricted to the administrator. The bot verifies the sender against the OWNER_USER_ID environment variable or a hardcoded fallback username.
• Output: It iterates through balance['total'] and filters for assets where the amount is greater than zero.

# Balance retrieval logic snippet
balance = _kucoin.fetch_balance()
has_assets = False
for asset, amount in balance['total'].items():
    if amount > 0:
        text += f"- {asset}: {amount}\n"
        has_assets = True

Sources: core/commands.py:104-133, tests/test_commands.py:220-270

Conclusion

The Crypto Portfolio Management module provides an integrated way to monitor market movements and manage personal KuCoin balances. By leveraging the ccxt library for market data and a PostgreSQL-backed monitoring thread for alerts, the system ensures that users stay informed of price fluctuations with minimal latency. High-level security checks on sensitive commands like /balance ensure that financial data remains restricted to authorized owners.

Sources: core/bot.py:1-85, core/commands.py:1-179