crypto_futures/AGENTS.md

Project Overview

Algorithmic trading bot platform with WebSocket-based real-time orderbook and trade data collection from multiple cryptocurrency exchanges. Uses TimescaleDB for archival, Redis for caching/messaging, and Celery for background tasks. Designed for momentum trading strategies with slippage prediction and dynamic trade execution across spot and futures markets.

Repository Structure

• docs/ - Documentation directory for architectural decisions and design notes
• modules/ - Python modules containing core functionality
• prompts/ - Visual diagrams and project documentation files
• tests/ - Test suite for validation
• requirements.txt - Python dependencies list
• Makefile - Build and development task automation
• README.rst - Project overview

Build & Development Commands

# Install dependencies
make init

# Run tests (currently stub - to be implemented)
make test

# Debug (future - see TODO: add pytest with debug flags or pdb integration)

Code Style & Conventions

Use Python typing (type hints for all functions), PEP 8 style guide, and module docstrings for clarity.

Naming: kebab-case for modules, snake_case for files, PascalCase for classes, camelCase for methods/variables.

Environment variables in .env file (never commit secrets). Use environment-based configuration.

Commit message format: <type>: <description> where type is one of (feat, fix, docs, refactor, test, chore).

Architecture Notes

+-------------------+      +------------------+
|     Exchange      |      |Exchange REST API |
|  WebSocket APIs   |      | trade endpoints  |
| (Binance,OKX,etc.)|      |(set/cancel trade)|
+-------------------+      +------------------+
       |                          ^
       v                          |
+-------------------+             |
| WebSocket Clients |             |
| (real-time data)  |             |
+-------------------+             |
       |                          |
       v                          |
+-------------------+      +------------------+
|       Redis       | ---> |  Celery Workers  |
|(Msg broker/Cache) |      |   (Processors)   |
+-------------------+      +------------------+
       ^                           |
       |                           v
       |                   +-------------------+
       +------------------ |   TimescaleDB     |
                           |    (Archive)      |
                           +-------------------+

Data Flow: Exchanges push real-time WebSocket messages to event handlers. Handlers publish events to Redis for Celery workers to consume. Workers process data, update archives in TimescaleDB, and trigger real-time strategy inference. Celery workers handle backtesting on historical data and trade execution.

Key Components:

• Exchange adapters: Uniform WebSocket handling for Binance/OKX/etc., minimizing exchange-specific logic
• Event handlers: Parse orderbook/trade events, implement reconnection/backoff
• Strategy engine: Momentum analysis, slippage prediction, order concentration detection
• Celery workers: Background data persistence, backtesting, trade execution coordination
• TimescaleDB: Time-series data storage for analysis and replaying
• Redis: In-memory cache and message queue infrastructure

Testing Strategy

Unit tests with pytest to test individual exchange adapters, event handlers, and strategy functions.

Integration tests verify Redis/TimescaleDB/Celery workflow with test fixtures.

TODO: Add CI/CD pipeline configuration and test coverage reporting (coverage.py + SonarQube).

Test data should be mock WebSocket responses for unit tests; real market data for integration tests with rate limiting.

Security & Compliance

TODO: Define and document API key handling strategy (encrypted environment variables, vault integration).

TODO: Implement dependency scanning with Snyk or similar.

TODO: Define data retention policies and privacy considerations.

Agent Guardrails

Never touch:

• Financial trading keys or secrets
• Dockerfile or Kubernetes deployment manifests until production ready
• CI/CD pipeline configuration files

Required reviews:

• PRs modifying core exchange adapters MUST be reviewed by lead engineer
• Changes to strategy logic require trading strategy team sign-off
• Any security-sensitive code requires security review

Extensibility Hooks

• SUPPORTED_EXCHANGES environment variable to configure supported exchanges.
• REDIS_URL and TIMESCALEDB_URL for cache and database connection configuration
• Strategy implementations exported via strategy_registry dictionary for plugin loading
• Celery broker url and backend configurable via environment variables

Further Reading

TODO: Create docs/ARCH.md for detailed architecture TODO: Add detailed API documentation in docs/API.md