# Bitfinex Maker-Kit
> **Modular Market Making Platform for Bitfinex**
A professional, production-ready command-line interface for automated trading and market making on the Bitfinex cryptocurrency exchange. Built with modern software architecture principles including dependency injection, domain-driven design, and comprehensive testing frameworks.
[](https://github.com/0xferit/bitfinex-maker-kit/stargazers)
[](https://github.com/0xferit/bitfinex-maker-kit/network/members)
[](https://github.com/0xferit/bitfinex-maker-kit/issues)
[](https://pypi.org/project/bitfinex-maker-kit/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## 🎯 Key Features
### 🛡️ Safety-First Architecture
- **POST_ONLY Enforcement**: Architecturally impossible to place market orders
- **Dry-Run Mode**: Test strategies without real trading
- **Multi-Layer Validation**: Domain objects, service layer, and API boundary validation
- **Risk Management**: Built-in safeguards and confirmation prompts
### ⚡ Modern Architecture
- **Dependency Injection**: Clean separation of concerns with container pattern
- **Domain-Driven Design**: Type-safe domain objects (OrderId, Price, Amount, Symbol)
- **Service-Oriented**: Modular services (trading, cache, market data, performance monitoring)
- **Event-Driven**: WebSocket integration with async event handling
### 🧪 Comprehensive Testing
- **Property-Based Testing**: 1000+ generated test cases using Hypothesis
- **Realistic Load Testing**: Integration tests against Bitfinex Paper Trading API
- **Performance Benchmarking**: Automated regression detection with real network conditions
- **Security Scanning**: Continuous vulnerability assessment
### 🚀 Production Ready
- **Modular Commands**: Extensible command system with core abstractions
- **Performance Monitoring**: Real-time metrics and profiling tools
- **Configuration Management**: Environment-aware configuration system
- **Quality Tooling**: Streamlined workflow with Ruff, MyPy, Bandit, and pytest
## 🏗️ Architecture Overview
### Modern Software Design
- **Safety First**: Architecturally enforced POST_ONLY orders with multiple validation layers
- **Modular Design**: Extensible architecture supporting multiple strategies and update methods
- **Domain-Driven**: Rich domain objects with business logic encapsulation
- **Service-Oriented**: Clean dependency injection with focused service responsibilities
### Core Architecture Components
#### 🎯 **Command Layer** (`commands/`)
- **Individual Commands**: `test`, `wallet`, `list`, `cancel`, `put`, `market-make`, `fill-spread`, `update`
- **Core Abstractions**: `core/` with base commands, executors, and result handling
- **Extensible Design**: Plugin-style command architecture
#### 🏛️ **Service Layer** (`services/`)
- **Container**: Dependency injection system managing service lifecycle
- **Trading Services**: Sync/async trading facades with monitoring
- **Cache Service**: Intelligent caching with namespace isolation
- **Performance Monitor**: Real-time metrics collection and analysis
- **Market Data Service**: Real-time price feeds and historical data
#### 🎨 **Domain Layer** (`domain/`)
- **Value Objects**: `OrderId`, `Price`, `Amount`, `Symbol` with validation
- **Business Logic**: Type-safe operations and domain rules
- **Immutable Design**: Functional programming principles
#### ⚙️ **Core Layer** (`core/`)
- **API Client**: Clean Bitfinex API wrapper with POST_ONLY enforcement
- **Trading Facade**: Unified interface coordinating focused components
- **Order Management**: Sophisticated order lifecycle management
- **Validation**: Multi-layer validation system
## 🛠️ Installation
### Production Installation
```bash
# Install with pipx (recommended)
pipx install bitfinex-maker-kit
# Configure API credentials
echo 'BITFINEX_API_KEY=your_api_key_here' > .env
echo 'BITFINEX_API_SECRET=your_api_secret_here' >> .env
```
### Development Installation
**Recommended: One-Command Setup** (solves externally-managed-environment errors)
```bash
# Clone repository
git clone https://github.com/0xferit/bitfinex-maker-kit.git
cd bitfinex-maker-kit
# One-command setup (creates venv + installs everything)
make setup
# Activate virtual environment (if not already active)
source venv/bin/activate # On Windows: venv\Scripts\activate
# Verify installation
make quality # Run all quality checks
pytest # Run tests
```
**Alternative: Using pipx** (for tool installation)
```bash
# Install as isolated application
pipx install git+https://github.com/0xferit/bitfinex-maker-kit.git
# For development
git clone https://github.com/0xferit/bitfinex-maker-kit.git
cd bitfinex-maker-kit
pipx install -e .
```
**Manual Installation** (if virtual environment setup fails)
```bash
# Option 1: Force install (not recommended)
pip install -e ".[dev]" --break-system-packages
# Option 2: User install
pip install -e ".[dev]" --user
# Option 3: Traditional virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
```
**💡 Troubleshooting "externally-managed-environment" Error:**
- **Modern Python/macOS**: Use virtual environment (recommended above)
- **System Python**: Use `pipx` for isolated installation
- **Docker**: Use the provided Dockerfile for containerized development
## 🚀 Quick Start
### Basic Usage
```bash
# Test API connection
bitfinex-maker-kit test
# View wallet balances
bitfinex-maker-kit wallet
# List active orders
bitfinex-maker-kit list
# Get help
bitfinex-maker-kit --help
```
### Market Making
```bash
# Create symmetric market making orders
bitfinex-maker-kit market-make --symbol tBTCUSD --levels 5 --spread 1.0 --size 0.1
# Start automated market making
bitfinex-maker-kit market-make --symbol tBTCUSD --levels 5
# Fill spread gaps
bitfinex-maker-kit fill-spread --symbol tETHUSD --levels 10
```
### Advanced Features
```bash
# Dry-run mode (recommended for testing)
bitfinex-maker-kit market-make --symbol tBTCUSD --levels 3 --dry-run
# Custom order placement
bitfinex-maker-kit put --symbol tBTCUSD --amount 0.01 --price 50000.0 --side buy
# Batch order cancellation
bitfinex-maker-kit cancel --symbol tBTCUSD --side buy
# Cancel all orders for a symbol
bitfinex-maker-kit cancel --all --symbol tBTCUSD
```
#### 🧩 **Strategies Layer** (`strategies/`, `update_strategies/`)
- **Order Generation**: Flexible order generation strategies
- **Update Strategies**: Multiple approaches (WebSocket, cancel-recreate, batch)
- **Strategy Factory**: Dynamic strategy selection based on market conditions
#### 🌐 **WebSocket Layer** (`websocket/`)
- **Connection Manager**: Robust WebSocket connection handling
- **Event Handler**: Real-time order updates and market data
- **Async Event Loop**: Non-blocking event processing
#### 🖥️ **UI Layer** (`ui/`)
- **Market Maker Console**: Interactive trading interface
- **Performance Dashboard**: Real-time metrics visualization
- **Profiler Integration**: Memory and performance monitoring
#### ⚙️ **Configuration Layer** (`config/`)
- **Environment Management**: Development, staging, production configs
- **Trading Configuration**: Dynamic configuration with validation
- **Feature Flags**: Environment-specific feature control
## 📋 Available Commands
| Command | Description | Architecture Features |
|---------|-------------|----------------------|
| `test` | Test API connection | Service container validation, credential testing |
| `wallet` | Show wallet balances | Real-time balance with caching and formatting |
| `list` | List active orders | Advanced filtering, display helpers, pagination |
| `cancel` | Cancel orders | Bulk operations, criteria matching, dry-run support, --all flag |
| `put` | Place single order | Domain validation, order builder pattern |
| `market-make` | Create staircase orders | Strategy-based generation, symmetric placement |
| `fill-spread` | Fill bid-ask gaps | Market data analysis, intelligent spacing |
| `update` | Update existing orders | Multiple update strategies, WebSocket optimization |
## 🧪 Testing & Quality Assurance
### Comprehensive Test Architecture
#### **Test Categories**
- **Unit Tests** (`tests/unit/`): Isolated component testing with mocks
- **Integration Tests** (`tests/integration/`): Service interaction validation
- **Property Tests** (`tests/property/`): Hypothesis-based fuzzing and edge cases
- **Load Tests** (`tests/load/`): Stress testing and traffic pattern simulation
- **Performance Tests** (`tests/performance/`): Benchmark suite with regression detection
- **Benchmarks** (`tests/benchmarks/`): Comprehensive performance analysis
#### **Test Infrastructure**
- **Fixtures** (`tests/fixtures/`): Reusable test data (API responses, market data, trading scenarios)
- **Mocks** (`tests/mocks/`): Service mocks (API, client, trading service, WebSocket)
- **Utilities** (`tests/utilities/`): Test helpers and profiling tools
#### **Specialized Testing**
- **POST_ONLY Enforcement**: Architectural safety validation
- **Python Version Compliance**: Version requirement testing
- **Wrapper Architecture**: API boundary validation
### Running Tests
```bash
# Run all tests with coverage
pytest --cov=bitfinex_maker_kit --cov-report=html
# Run specific test categories
pytest tests/unit/ # Unit tests
pytest tests/integration/ # Integration tests
pytest tests/property/ # Property-based tests
pytest tests/load/ # Load and stress tests
pytest tests/performance/ # Performance benchmarks
# Run with markers
pytest -m unit # Unit tests only
pytest -m integration # Integration tests
pytest -m property # Property-based tests
pytest -m load # Load tests
pytest -m benchmark # Performance benchmarks
# Run specific architectural tests
pytest tests/test_post_only_enforcement.py # Safety validation
pytest tests/test_wrapper_architecture.py # Architecture validation
pytest tests/test_python_version_requirement.py # Version compliance
```
### Code Quality - Simple Workflow
**Three commands for everything:**
```bash
# Quick setup
make install # Install all dev dependencies
# Main workflow
make quality # Run all quality checks (recommended)
make test # Run tests with coverage
# Individual checks (if needed)
make format # Auto-format code
make lint # Run linter with auto-fix
make type-check # Run type checking
make security # Run security scan
```
**Alternative: Direct commands**
```bash
# All-in-one linter and formatter (replaces black, isort, flake8)
ruff check . --fix # Lint with auto-fix
ruff format . # Format code
# Type checking and security
mypy bitfinex_maker_kit/ # Type checking
bandit -r bitfinex_maker_kit/ # Security scan
```
**Quick validation** (30 seconds):
```bash
./scripts/check.sh # Fast pre-commit check
```
## 📊 Performance Monitoring & Observability
### Built-in Performance Infrastructure
#### **Performance Monitor Service** (`services/performance_monitor.py`)
- **Real-Time Metrics**: P50, P95, P99 percentiles for API operations
- **Cache Analytics**: Hit ratios, miss patterns, namespace efficiency
- **Memory Profiling**: Leak detection with heap snapshots
- **Error Tracking**: Success/failure rates with categorization
#### **Profiler Utilities** (`utilities/profiler.py`)
- **Execution Profiling**: Function-level performance analysis
- **Memory Monitoring**: Detailed memory usage tracking
- **Bottleneck Detection**: Automated performance regression alerts
- **Resource Utilization**: CPU, memory, and I/O monitoring
#### **Performance Dashboard** (`utilities/performance_dashboard.py`)
- **Real-Time Visualization**: Live metrics display
- **Historical Analysis**: Performance trend tracking
- **Alert System**: Automated threshold-based notifications
- **Export Capabilities**: JSON, CSV data export
#### **Market Data Caching** (`utilities/market_data_cache.py`)
- **Intelligent Caching**: 90%+ API call reduction
- **Cache Warming**: Proactive data prefetching
- **Namespace Isolation**: Multi-symbol cache management
- **TTL Management**: Automatic cache invalidation
### Using Performance Tools
```bash
# Enable performance monitoring in commands
bitfinex-maker-kit market-make --enable-monitoring
# View performance metrics (via dashboard integration)
# Dashboard accessible through market-make UI console
# Load testing and benchmarks
pytest tests/performance/ --benchmark-json=results.json
pytest tests/load/ -v # Stress testing
```
## 🔒 Security Features
### Built-in Security
- **POST_ONLY Orders**: Market orders architecturally impossible
- **API Key Protection**: Secure credential management
- **Input Validation**: Comprehensive parameter validation
- **Rate Limiting**: API abuse prevention
- **Audit Logging**: Complete operation tracking
### Security Scanning
- **Dependency Scanning**: Automated vulnerability detection
- **Code Analysis**: Static security analysis with Bandit
- **Secret Detection**: Credential leak prevention
- **License Compliance**: MIT license for maximum flexibility
## 🐳 Docker Deployment
### Docker Usage
```bash
# Build image
docker build -t bitfinex-maker-kit .
# Run container
docker run -d \
--name bitfinex-maker-kit \
-e BITFINEX_API_KEY=your_key \
-e BITFINEX_API_SECRET=your_secret \
bitfinex-maker-kit
# View logs
docker logs bitfinex-maker-kit
```
### Docker Compose
```yaml
version: '3.8'
services:
bitfinex-maker-kit:
build: .
environment:
- BITFINEX_API_KEY=${BITFINEX_API_KEY}
- BITFINEX_API_SECRET=${BITFINEX_API_SECRET}
volumes:
- ./logs:/app/logs
restart: unless-stopped
```
## 📈 Performance Benchmarks
### Typical Performance Metrics
- **Order Placement**: 100+ orders/second
- **API Response Time**: <50ms P95
- **Cache Hit Ratio**: >90%
- **Memory Usage**: <100MB steady state
- **Error Rate**: <0.1% under normal conditions
### Load Testing Results
- **Constant Load**: 1000+ operations sustained
- **Burst Load**: 5000+ operations peak
- **Stress Test**: 99%+ uptime under extreme load
- **Memory Efficiency**: No memory leaks detected
## 🤝 Contributing
### Development Setup
```bash
# Install development dependencies
pip install -e ".[dev,test,security]"
# Install pre-commit hooks
pre-commit install
# Run full test suite
tox
```
### Code Standards
- **Python 3.12+** required
- **Type hints** mandatory
- **100% test coverage** for new features
- **Security review** for all changes
- **Performance benchmarks** for optimizations
### Pull Request Process
1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Make changes with tests and documentation
4. Run quality checks: `tox`
5. Submit pull request with detailed description
## 📖 Codebase Structure
### Directory Organization
```
bitfinex_maker_kit/
├── __init__.py # Package entry point and exports
├── cli.py # Main CLI interface using focused components
├── bitfinex_client.py # Legacy wrapper (delegating to core/)
├── cli/ # CLI-specific components
│ ├── argument_parser.py # Command-line argument parsing
│ └── command_router.py # Command routing logic
├── commands/ # Individual command implementations
│ ├── core/ # Command abstractions and patterns
│ │ ├── base_command.py # Base command interface
│ │ ├── command_executor.py # Command execution framework
│ │ ├── command_result.py # Result handling
│ │ └── [specialized_commands] # Command implementations
│ └── [individual_commands].py # Main CLI commands
├── core/ # Core business logic
│ ├── api_client.py # Clean Bitfinex API wrapper
│ ├── trading_facade.py # Unified trading interface
│ ├── order_manager.py # Order lifecycle management
│ └── order_validator.py # Multi-layer validation
├── domain/ # Domain objects and business rules
│ ├── order_id.py # Order identification value object
│ ├── price.py # Price value object with validation
│ ├── amount.py # Amount value object with validation
│ └── symbol.py # Trading pair symbol validation
├── services/ # Service layer with dependency injection
│ ├── container.py # Dependency injection container
│ ├── trading_service.py # Core trading operations
│ ├── cache_service.py # Intelligent caching system
│ └── performance_monitor.py # Real-time metrics collection
├── strategies/ # Trading strategy implementations
│ └── order_generator.py # Flexible order generation
├── update_strategies/ # Order update approaches
│ ├── base.py # Update strategy interface
│ ├── websocket_strategy.py # Real-time WebSocket updates
│ └── cancel_recreate_strategy.py # Cancel-recreate fallback
├── websocket/ # WebSocket integration
│ ├── connection_manager.py # Connection lifecycle
│ └── event_handler.py # Real-time event processing
├── ui/ # User interface components
│ └── market_maker_console.py # Interactive trading console
├── config/ # Configuration management
│ ├── environment.py # Environment-aware configuration
│ └── trading_config.py # Trading-specific settings
└── utilities/ # Shared utilities and helpers
├── [various_utilities].py # Helper functions and utilities
├── performance_dashboard.py # Performance visualization
└── profiler.py # Performance profiling tools
```
### Key Design Patterns
- **Dependency Injection**: Clean service boundaries with container pattern
- **Command Pattern**: Extensible command system with undo capabilities
- **Strategy Pattern**: Pluggable algorithms for order generation and updates
- **Facade Pattern**: Simplified interfaces over complex subsystems
- **Domain-Driven Design**: Rich domain objects with business logic
## 🤝 Contributing
We welcome contributions! This project uses automated semantic versioning and release management.
### Development Workflow
1. **Fork and Clone**: Fork the repository and clone locally
2. **Create Feature Branch**: Branch from `develop` for new features
3. **Write Code**: Follow existing patterns and conventions
4. **Test Thoroughly**: Ensure all tests pass with `pytest`
5. **Submit PR**: Open a pull request to `develop` branch
### Conventional Commits
We use [Conventional Commits](https://www.conventionalcommits.org/) for automated versioning. Your commit messages determine version bumps:
| Commit Type | Example | Version Bump |
|------------|---------|--------------|
| `fix:` | `fix: correct order cancellation logic` | Patch (0.0.X) |
| `feat:` | `feat: add stop-loss order support` | Minor (0.X.0) |
| `BREAKING CHANGE:` | `feat!: change API response format` | Major (X.0.0) |
| `chore:` | `chore: update dependencies` | No release |
| `docs:` | `docs: improve API documentation` | No release |
| `test:` | `test: add integration tests` | No release |
| `refactor:` | `refactor: simplify order validation` | Patch (0.0.X) |
| `perf:` | `perf: optimize WebSocket handling` | Patch (0.0.X) |
#### Examples
```bash
# Bug fix (patch release)
git commit -m "fix: resolve WebSocket reconnection issue"
# New feature (minor release)
git commit -m "feat: implement adaptive spread adjustment"
# Breaking change (major release)
git commit -m "feat!: redesign order management API
BREAKING CHANGE: OrderManager.create() now requires Symbol parameter"
# No release
git commit -m "docs: add examples for market-make command"
git commit -m "chore: update ruff configuration"
```
### Automated Release Process
When changes are merged from `develop` to `main`:
1. The system analyzes commit messages since the last release
2. Automatically determines the version bump type
3. Updates version in `pyproject.toml` and `__init__.py`
4. Creates a git tag
5. Publishes to PyPI
6. Creates a GitHub release
No manual version management needed!
## ⚠️ Risk Disclaimer
**IMPORTANT**: Trading cryptocurrency involves substantial risk of loss and is not suitable for every investor. The volatile nature of cryptocurrency markets may result in significant financial losses. You should carefully consider whether trading is suitable for you in light of your circumstances, knowledge, and financial resources.
- **Test First**: Always use `--dry-run` mode before live trading
- **Start Small**: Begin with minimal position sizes
- **Monitor Closely**: Actively supervise automated strategies
- **Risk Management**: Never trade more than you can afford to lose
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
### Third-Party Dependencies
All dependencies use compatible permissive licenses (MIT, BSD, Apache-2.0). See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for complete license attributions.
## 🙏 Acknowledgments
- **Bitfinex API Team** for comprehensive API documentation
- **Open Source Community** for testing frameworks and tools
- **Security Researchers** for vulnerability disclosure
- **Trading Community** for feature requests and feedback
---
**Ready for Enterprise Trading!** 🚀
Start with `bitfinex-maker-kit test` to verify your setup, then explore the comprehensive feature set designed for professional market making.
Raw data
{
"_id": null,
"home_page": null,
"name": "bitfinex-maker-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "bitfinex, cryptocurrency, trading, market-making, automated-trading",
"author": "Bitfinex Maker-Kit Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b4/91/0a0a3aab915f44202817a3a27d29fd396046848474cfad0cce77f45401e6/bitfinex_maker_kit-4.7.0.tar.gz",
"platform": null,
"description": "# Bitfinex Maker-Kit\n\n> **Modular Market Making Platform for Bitfinex**\n\nA professional, production-ready command-line interface for automated trading and market making on the Bitfinex cryptocurrency exchange. Built with modern software architecture principles including dependency injection, domain-driven design, and comprehensive testing frameworks.\n\n[](https://github.com/0xferit/bitfinex-maker-kit/stargazers)\n[](https://github.com/0xferit/bitfinex-maker-kit/network/members)\n[](https://github.com/0xferit/bitfinex-maker-kit/issues)\n[](https://pypi.org/project/bitfinex-maker-kit/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n## \ud83c\udfaf Key Features\n\n### \ud83d\udee1\ufe0f Safety-First Architecture\n- **POST_ONLY Enforcement**: Architecturally impossible to place market orders\n- **Dry-Run Mode**: Test strategies without real trading\n- **Multi-Layer Validation**: Domain objects, service layer, and API boundary validation\n- **Risk Management**: Built-in safeguards and confirmation prompts\n\n### \u26a1 Modern Architecture\n- **Dependency Injection**: Clean separation of concerns with container pattern\n- **Domain-Driven Design**: Type-safe domain objects (OrderId, Price, Amount, Symbol)\n- **Service-Oriented**: Modular services (trading, cache, market data, performance monitoring)\n- **Event-Driven**: WebSocket integration with async event handling\n\n### \ud83e\uddea Comprehensive Testing\n- **Property-Based Testing**: 1000+ generated test cases using Hypothesis\n- **Realistic Load Testing**: Integration tests against Bitfinex Paper Trading API\n- **Performance Benchmarking**: Automated regression detection with real network conditions\n- **Security Scanning**: Continuous vulnerability assessment\n\n### \ud83d\ude80 Production Ready\n- **Modular Commands**: Extensible command system with core abstractions\n- **Performance Monitoring**: Real-time metrics and profiling tools\n- **Configuration Management**: Environment-aware configuration system\n- **Quality Tooling**: Streamlined workflow with Ruff, MyPy, Bandit, and pytest\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\n### Modern Software Design\n- **Safety First**: Architecturally enforced POST_ONLY orders with multiple validation layers\n- **Modular Design**: Extensible architecture supporting multiple strategies and update methods\n- **Domain-Driven**: Rich domain objects with business logic encapsulation\n- **Service-Oriented**: Clean dependency injection with focused service responsibilities\n\n### Core Architecture Components\n\n#### \ud83c\udfaf **Command Layer** (`commands/`)\n- **Individual Commands**: `test`, `wallet`, `list`, `cancel`, `put`, `market-make`, `fill-spread`, `update`\n- **Core Abstractions**: `core/` with base commands, executors, and result handling\n- **Extensible Design**: Plugin-style command architecture\n\n#### \ud83c\udfdb\ufe0f **Service Layer** (`services/`)\n- **Container**: Dependency injection system managing service lifecycle\n- **Trading Services**: Sync/async trading facades with monitoring\n- **Cache Service**: Intelligent caching with namespace isolation\n- **Performance Monitor**: Real-time metrics collection and analysis\n- **Market Data Service**: Real-time price feeds and historical data\n\n#### \ud83c\udfa8 **Domain Layer** (`domain/`)\n- **Value Objects**: `OrderId`, `Price`, `Amount`, `Symbol` with validation\n- **Business Logic**: Type-safe operations and domain rules\n- **Immutable Design**: Functional programming principles\n\n#### \u2699\ufe0f **Core Layer** (`core/`)\n- **API Client**: Clean Bitfinex API wrapper with POST_ONLY enforcement\n- **Trading Facade**: Unified interface coordinating focused components\n- **Order Management**: Sophisticated order lifecycle management\n- **Validation**: Multi-layer validation system\n\n## \ud83d\udee0\ufe0f Installation\n\n### Production Installation\n```bash\n# Install with pipx (recommended)\npipx install bitfinex-maker-kit\n\n# Configure API credentials\necho 'BITFINEX_API_KEY=your_api_key_here' > .env\necho 'BITFINEX_API_SECRET=your_api_secret_here' >> .env\n```\n\n### Development Installation\n\n**Recommended: One-Command Setup** (solves externally-managed-environment errors)\n```bash\n# Clone repository\ngit clone https://github.com/0xferit/bitfinex-maker-kit.git\ncd bitfinex-maker-kit\n\n# One-command setup (creates venv + installs everything)\nmake setup\n\n# Activate virtual environment (if not already active)\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Verify installation\nmake quality # Run all quality checks\npytest # Run tests\n```\n\n**Alternative: Using pipx** (for tool installation)\n```bash\n# Install as isolated application\npipx install git+https://github.com/0xferit/bitfinex-maker-kit.git\n\n# For development\ngit clone https://github.com/0xferit/bitfinex-maker-kit.git\ncd bitfinex-maker-kit\npipx install -e .\n```\n\n**Manual Installation** (if virtual environment setup fails)\n```bash\n# Option 1: Force install (not recommended)\npip install -e \".[dev]\" --break-system-packages\n\n# Option 2: User install\npip install -e \".[dev]\" --user\n\n# Option 3: Traditional virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\npre-commit install\n```\n\n**\ud83d\udca1 Troubleshooting \"externally-managed-environment\" Error:**\n- **Modern Python/macOS**: Use virtual environment (recommended above)\n- **System Python**: Use `pipx` for isolated installation \n- **Docker**: Use the provided Dockerfile for containerized development\n\n## \ud83d\ude80 Quick Start\n\n### Basic Usage\n```bash\n# Test API connection\nbitfinex-maker-kit test\n\n# View wallet balances\nbitfinex-maker-kit wallet\n\n# List active orders\nbitfinex-maker-kit list\n\n# Get help\nbitfinex-maker-kit --help\n```\n\n### Market Making\n```bash\n# Create symmetric market making orders\nbitfinex-maker-kit market-make --symbol tBTCUSD --levels 5 --spread 1.0 --size 0.1\n\n# Start automated market making\nbitfinex-maker-kit market-make --symbol tBTCUSD --levels 5\n\n# Fill spread gaps\nbitfinex-maker-kit fill-spread --symbol tETHUSD --levels 10\n```\n\n### Advanced Features\n```bash\n# Dry-run mode (recommended for testing)\nbitfinex-maker-kit market-make --symbol tBTCUSD --levels 3 --dry-run\n\n# Custom order placement\nbitfinex-maker-kit put --symbol tBTCUSD --amount 0.01 --price 50000.0 --side buy\n\n# Batch order cancellation\nbitfinex-maker-kit cancel --symbol tBTCUSD --side buy\n\n# Cancel all orders for a symbol\nbitfinex-maker-kit cancel --all --symbol tBTCUSD\n```\n\n#### \ud83e\udde9 **Strategies Layer** (`strategies/`, `update_strategies/`)\n- **Order Generation**: Flexible order generation strategies\n- **Update Strategies**: Multiple approaches (WebSocket, cancel-recreate, batch)\n- **Strategy Factory**: Dynamic strategy selection based on market conditions\n\n#### \ud83c\udf10 **WebSocket Layer** (`websocket/`)\n- **Connection Manager**: Robust WebSocket connection handling\n- **Event Handler**: Real-time order updates and market data\n- **Async Event Loop**: Non-blocking event processing\n\n#### \ud83d\udda5\ufe0f **UI Layer** (`ui/`)\n- **Market Maker Console**: Interactive trading interface\n- **Performance Dashboard**: Real-time metrics visualization\n- **Profiler Integration**: Memory and performance monitoring\n\n#### \u2699\ufe0f **Configuration Layer** (`config/`)\n- **Environment Management**: Development, staging, production configs\n- **Trading Configuration**: Dynamic configuration with validation\n- **Feature Flags**: Environment-specific feature control\n\n## \ud83d\udccb Available Commands\n\n| Command | Description | Architecture Features |\n|---------|-------------|----------------------|\n| `test` | Test API connection | Service container validation, credential testing |\n| `wallet` | Show wallet balances | Real-time balance with caching and formatting |\n| `list` | List active orders | Advanced filtering, display helpers, pagination |\n| `cancel` | Cancel orders | Bulk operations, criteria matching, dry-run support, --all flag |\n| `put` | Place single order | Domain validation, order builder pattern |\n| `market-make` | Create staircase orders | Strategy-based generation, symmetric placement |\n| `fill-spread` | Fill bid-ask gaps | Market data analysis, intelligent spacing |\n| `update` | Update existing orders | Multiple update strategies, WebSocket optimization |\n\n## \ud83e\uddea Testing & Quality Assurance\n\n### Comprehensive Test Architecture\n\n#### **Test Categories**\n- **Unit Tests** (`tests/unit/`): Isolated component testing with mocks\n- **Integration Tests** (`tests/integration/`): Service interaction validation\n- **Property Tests** (`tests/property/`): Hypothesis-based fuzzing and edge cases\n- **Load Tests** (`tests/load/`): Stress testing and traffic pattern simulation\n- **Performance Tests** (`tests/performance/`): Benchmark suite with regression detection\n- **Benchmarks** (`tests/benchmarks/`): Comprehensive performance analysis\n\n#### **Test Infrastructure**\n- **Fixtures** (`tests/fixtures/`): Reusable test data (API responses, market data, trading scenarios)\n- **Mocks** (`tests/mocks/`): Service mocks (API, client, trading service, WebSocket)\n- **Utilities** (`tests/utilities/`): Test helpers and profiling tools\n\n#### **Specialized Testing**\n- **POST_ONLY Enforcement**: Architectural safety validation\n- **Python Version Compliance**: Version requirement testing\n- **Wrapper Architecture**: API boundary validation\n\n### Running Tests\n```bash\n# Run all tests with coverage\npytest --cov=bitfinex_maker_kit --cov-report=html\n\n# Run specific test categories\npytest tests/unit/ # Unit tests\npytest tests/integration/ # Integration tests \npytest tests/property/ # Property-based tests\npytest tests/load/ # Load and stress tests\npytest tests/performance/ # Performance benchmarks\n\n# Run with markers\npytest -m unit # Unit tests only\npytest -m integration # Integration tests\npytest -m property # Property-based tests\npytest -m load # Load tests\npytest -m benchmark # Performance benchmarks\n\n# Run specific architectural tests\npytest tests/test_post_only_enforcement.py # Safety validation\npytest tests/test_wrapper_architecture.py # Architecture validation\npytest tests/test_python_version_requirement.py # Version compliance\n```\n\n### Code Quality - Simple Workflow\n\n**Three commands for everything:**\n```bash\n# Quick setup\nmake install # Install all dev dependencies\n\n# Main workflow \nmake quality # Run all quality checks (recommended)\nmake test # Run tests with coverage\n\n# Individual checks (if needed)\nmake format # Auto-format code\nmake lint # Run linter with auto-fix\nmake type-check # Run type checking\nmake security # Run security scan\n```\n\n**Alternative: Direct commands**\n```bash\n# All-in-one linter and formatter (replaces black, isort, flake8)\nruff check . --fix # Lint with auto-fix\nruff format . # Format code\n\n# Type checking and security\nmypy bitfinex_maker_kit/ # Type checking\nbandit -r bitfinex_maker_kit/ # Security scan\n```\n\n**Quick validation** (30 seconds):\n```bash\n./scripts/check.sh # Fast pre-commit check\n```\n\n## \ud83d\udcca Performance Monitoring & Observability\n\n### Built-in Performance Infrastructure\n\n#### **Performance Monitor Service** (`services/performance_monitor.py`)\n- **Real-Time Metrics**: P50, P95, P99 percentiles for API operations\n- **Cache Analytics**: Hit ratios, miss patterns, namespace efficiency\n- **Memory Profiling**: Leak detection with heap snapshots\n- **Error Tracking**: Success/failure rates with categorization\n\n#### **Profiler Utilities** (`utilities/profiler.py`)\n- **Execution Profiling**: Function-level performance analysis\n- **Memory Monitoring**: Detailed memory usage tracking\n- **Bottleneck Detection**: Automated performance regression alerts\n- **Resource Utilization**: CPU, memory, and I/O monitoring\n\n#### **Performance Dashboard** (`utilities/performance_dashboard.py`)\n- **Real-Time Visualization**: Live metrics display\n- **Historical Analysis**: Performance trend tracking\n- **Alert System**: Automated threshold-based notifications\n- **Export Capabilities**: JSON, CSV data export\n\n#### **Market Data Caching** (`utilities/market_data_cache.py`)\n- **Intelligent Caching**: 90%+ API call reduction\n- **Cache Warming**: Proactive data prefetching \n- **Namespace Isolation**: Multi-symbol cache management\n- **TTL Management**: Automatic cache invalidation\n\n### Using Performance Tools\n```bash\n# Enable performance monitoring in commands\nbitfinex-maker-kit market-make --enable-monitoring\n\n# View performance metrics (via dashboard integration)\n# Dashboard accessible through market-make UI console\n\n# Load testing and benchmarks\npytest tests/performance/ --benchmark-json=results.json\npytest tests/load/ -v # Stress testing\n```\n\n## \ud83d\udd12 Security Features\n\n### Built-in Security\n- **POST_ONLY Orders**: Market orders architecturally impossible\n- **API Key Protection**: Secure credential management\n- **Input Validation**: Comprehensive parameter validation\n- **Rate Limiting**: API abuse prevention\n- **Audit Logging**: Complete operation tracking\n\n### Security Scanning\n- **Dependency Scanning**: Automated vulnerability detection\n- **Code Analysis**: Static security analysis with Bandit\n- **Secret Detection**: Credential leak prevention\n- **License Compliance**: MIT license for maximum flexibility\n\n## \ud83d\udc33 Docker Deployment\n\n### Docker Usage\n```bash\n# Build image\ndocker build -t bitfinex-maker-kit .\n\n# Run container\ndocker run -d \\\n --name bitfinex-maker-kit \\\n -e BITFINEX_API_KEY=your_key \\\n -e BITFINEX_API_SECRET=your_secret \\\n bitfinex-maker-kit\n\n# View logs\ndocker logs bitfinex-maker-kit\n```\n\n### Docker Compose\n```yaml\nversion: '3.8'\nservices:\n bitfinex-maker-kit:\n build: .\n environment:\n - BITFINEX_API_KEY=${BITFINEX_API_KEY}\n - BITFINEX_API_SECRET=${BITFINEX_API_SECRET}\n volumes:\n - ./logs:/app/logs\n restart: unless-stopped\n```\n\n## \ud83d\udcc8 Performance Benchmarks\n\n### Typical Performance Metrics\n- **Order Placement**: 100+ orders/second\n- **API Response Time**: <50ms P95\n- **Cache Hit Ratio**: >90%\n- **Memory Usage**: <100MB steady state\n- **Error Rate**: <0.1% under normal conditions\n\n### Load Testing Results\n- **Constant Load**: 1000+ operations sustained\n- **Burst Load**: 5000+ operations peak\n- **Stress Test**: 99%+ uptime under extreme load\n- **Memory Efficiency**: No memory leaks detected\n\n## \ud83e\udd1d Contributing\n\n### Development Setup\n```bash\n# Install development dependencies\npip install -e \".[dev,test,security]\"\n\n# Install pre-commit hooks\npre-commit install\n\n# Run full test suite\ntox\n```\n\n### Code Standards\n- **Python 3.12+** required\n- **Type hints** mandatory\n- **100% test coverage** for new features\n- **Security review** for all changes\n- **Performance benchmarks** for optimizations\n\n### Pull Request Process\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/amazing-feature`\n3. Make changes with tests and documentation\n4. Run quality checks: `tox`\n5. Submit pull request with detailed description\n\n## \ud83d\udcd6 Codebase Structure\n\n### Directory Organization\n```\nbitfinex_maker_kit/\n\u251c\u2500\u2500 __init__.py # Package entry point and exports\n\u251c\u2500\u2500 cli.py # Main CLI interface using focused components\n\u251c\u2500\u2500 bitfinex_client.py # Legacy wrapper (delegating to core/)\n\u251c\u2500\u2500 cli/ # CLI-specific components\n\u2502 \u251c\u2500\u2500 argument_parser.py # Command-line argument parsing\n\u2502 \u2514\u2500\u2500 command_router.py # Command routing logic\n\u251c\u2500\u2500 commands/ # Individual command implementations\n\u2502 \u251c\u2500\u2500 core/ # Command abstractions and patterns\n\u2502 \u2502 \u251c\u2500\u2500 base_command.py # Base command interface\n\u2502 \u2502 \u251c\u2500\u2500 command_executor.py # Command execution framework\n\u2502 \u2502 \u251c\u2500\u2500 command_result.py # Result handling\n\u2502 \u2502 \u2514\u2500\u2500 [specialized_commands] # Command implementations\n\u2502 \u2514\u2500\u2500 [individual_commands].py # Main CLI commands\n\u251c\u2500\u2500 core/ # Core business logic\n\u2502 \u251c\u2500\u2500 api_client.py # Clean Bitfinex API wrapper\n\u2502 \u251c\u2500\u2500 trading_facade.py # Unified trading interface\n\u2502 \u251c\u2500\u2500 order_manager.py # Order lifecycle management\n\u2502 \u2514\u2500\u2500 order_validator.py # Multi-layer validation\n\u251c\u2500\u2500 domain/ # Domain objects and business rules\n\u2502 \u251c\u2500\u2500 order_id.py # Order identification value object\n\u2502 \u251c\u2500\u2500 price.py # Price value object with validation\n\u2502 \u251c\u2500\u2500 amount.py # Amount value object with validation\n\u2502 \u2514\u2500\u2500 symbol.py # Trading pair symbol validation\n\u251c\u2500\u2500 services/ # Service layer with dependency injection\n\u2502 \u251c\u2500\u2500 container.py # Dependency injection container\n\u2502 \u251c\u2500\u2500 trading_service.py # Core trading operations\n\u2502 \u251c\u2500\u2500 cache_service.py # Intelligent caching system\n\u2502 \u2514\u2500\u2500 performance_monitor.py # Real-time metrics collection\n\u251c\u2500\u2500 strategies/ # Trading strategy implementations\n\u2502 \u2514\u2500\u2500 order_generator.py # Flexible order generation\n\u251c\u2500\u2500 update_strategies/ # Order update approaches\n\u2502 \u251c\u2500\u2500 base.py # Update strategy interface\n\u2502 \u251c\u2500\u2500 websocket_strategy.py # Real-time WebSocket updates\n\u2502 \u2514\u2500\u2500 cancel_recreate_strategy.py # Cancel-recreate fallback\n\u251c\u2500\u2500 websocket/ # WebSocket integration\n\u2502 \u251c\u2500\u2500 connection_manager.py # Connection lifecycle\n\u2502 \u2514\u2500\u2500 event_handler.py # Real-time event processing\n\u251c\u2500\u2500 ui/ # User interface components\n\u2502 \u2514\u2500\u2500 market_maker_console.py # Interactive trading console\n\u251c\u2500\u2500 config/ # Configuration management\n\u2502 \u251c\u2500\u2500 environment.py # Environment-aware configuration\n\u2502 \u2514\u2500\u2500 trading_config.py # Trading-specific settings\n\u2514\u2500\u2500 utilities/ # Shared utilities and helpers\n \u251c\u2500\u2500 [various_utilities].py # Helper functions and utilities\n \u251c\u2500\u2500 performance_dashboard.py # Performance visualization\n \u2514\u2500\u2500 profiler.py # Performance profiling tools\n```\n\n### Key Design Patterns\n- **Dependency Injection**: Clean service boundaries with container pattern\n- **Command Pattern**: Extensible command system with undo capabilities \n- **Strategy Pattern**: Pluggable algorithms for order generation and updates\n- **Facade Pattern**: Simplified interfaces over complex subsystems\n- **Domain-Driven Design**: Rich domain objects with business logic\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! This project uses automated semantic versioning and release management.\n\n### Development Workflow\n\n1. **Fork and Clone**: Fork the repository and clone locally\n2. **Create Feature Branch**: Branch from `develop` for new features\n3. **Write Code**: Follow existing patterns and conventions\n4. **Test Thoroughly**: Ensure all tests pass with `pytest`\n5. **Submit PR**: Open a pull request to `develop` branch\n\n### Conventional Commits\n\nWe use [Conventional Commits](https://www.conventionalcommits.org/) for automated versioning. Your commit messages determine version bumps:\n\n| Commit Type | Example | Version Bump |\n|------------|---------|--------------|\n| `fix:` | `fix: correct order cancellation logic` | Patch (0.0.X) |\n| `feat:` | `feat: add stop-loss order support` | Minor (0.X.0) |\n| `BREAKING CHANGE:` | `feat!: change API response format` | Major (X.0.0) |\n| `chore:` | `chore: update dependencies` | No release |\n| `docs:` | `docs: improve API documentation` | No release |\n| `test:` | `test: add integration tests` | No release |\n| `refactor:` | `refactor: simplify order validation` | Patch (0.0.X) |\n| `perf:` | `perf: optimize WebSocket handling` | Patch (0.0.X) |\n\n#### Examples\n\n```bash\n# Bug fix (patch release)\ngit commit -m \"fix: resolve WebSocket reconnection issue\"\n\n# New feature (minor release)\ngit commit -m \"feat: implement adaptive spread adjustment\"\n\n# Breaking change (major release)\ngit commit -m \"feat!: redesign order management API\n\nBREAKING CHANGE: OrderManager.create() now requires Symbol parameter\"\n\n# No release\ngit commit -m \"docs: add examples for market-make command\"\ngit commit -m \"chore: update ruff configuration\"\n```\n\n### Automated Release Process\n\nWhen changes are merged from `develop` to `main`:\n1. The system analyzes commit messages since the last release\n2. Automatically determines the version bump type\n3. Updates version in `pyproject.toml` and `__init__.py`\n4. Creates a git tag\n5. Publishes to PyPI\n6. Creates a GitHub release\n\nNo manual version management needed!\n\n## \u26a0\ufe0f Risk Disclaimer\n\n**IMPORTANT**: Trading cryptocurrency involves substantial risk of loss and is not suitable for every investor. The volatile nature of cryptocurrency markets may result in significant financial losses. You should carefully consider whether trading is suitable for you in light of your circumstances, knowledge, and financial resources.\n\n- **Test First**: Always use `--dry-run` mode before live trading\n- **Start Small**: Begin with minimal position sizes\n- **Monitor Closely**: Actively supervise automated strategies\n- **Risk Management**: Never trade more than you can afford to lose\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n### Third-Party Dependencies\nAll dependencies use compatible permissive licenses (MIT, BSD, Apache-2.0). See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for complete license attributions.\n\n## \ud83d\ude4f Acknowledgments\n\n- **Bitfinex API Team** for comprehensive API documentation\n- **Open Source Community** for testing frameworks and tools\n- **Security Researchers** for vulnerability disclosure\n- **Trading Community** for feature requests and feedback\n\n---\n\n**Ready for Enterprise Trading!** \ud83d\ude80\n\nStart with `bitfinex-maker-kit test` to verify your setup, then explore the comprehensive feature set designed for professional market making. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional market making toolkit for Bitfinex cryptocurrency exchange",
"version": "4.7.0",
"project_urls": null,
"split_keywords": [
"bitfinex",
" cryptocurrency",
" trading",
" market-making",
" automated-trading"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7ad5c5173fc35257bbfad20872f1ca7cdb873c9e3183d0ef075905936da29b8e",
"md5": "5175918878b3d25d32698a9472ab6d44",
"sha256": "9c85d08d3aa7d3d212b4237efe5ac8b0f3ae3a2d49368f68800890f6a2b732ce"
},
"downloads": -1,
"filename": "bitfinex_maker_kit-4.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5175918878b3d25d32698a9472ab6d44",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 178637,
"upload_time": "2025-08-23T23:20:36",
"upload_time_iso_8601": "2025-08-23T23:20:36.953425Z",
"url": "https://files.pythonhosted.org/packages/7a/d5/c5173fc35257bbfad20872f1ca7cdb873c9e3183d0ef075905936da29b8e/bitfinex_maker_kit-4.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b4910a0a3aab915f44202817a3a27d29fd396046848474cfad0cce77f45401e6",
"md5": "1ba39e0d1bc2673b29053098e07f1c48",
"sha256": "7807e20c226917350c2866290425ca9a8612da4d4f66327e27f5bea20cbcf615"
},
"downloads": -1,
"filename": "bitfinex_maker_kit-4.7.0.tar.gz",
"has_sig": false,
"md5_digest": "1ba39e0d1bc2673b29053098e07f1c48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 158339,
"upload_time": "2025-08-23T23:20:38",
"upload_time_iso_8601": "2025-08-23T23:20:38.668959Z",
"url": "https://files.pythonhosted.org/packages/b4/91/0a0a3aab915f44202817a3a27d29fd396046848474cfad0cce77f45401e6/bitfinex_maker_kit-4.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 23:20:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bitfinex-maker-kit"
}
JSON