Metadata-Version: 2.4
Name: ccxao
Version: 0.1.75
Summary: CCXAO - CryptoCurrency eXchange Algoritmic Orders
Author-email: Ricardo Marcelo Alvarez <rmalvarezkai@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: <=3.14,>=3.13
Requires-Dist: binance-fix-connector>=1.2.0
Requires-Dist: ccxt>=4.5.51
Requires-Dist: ccxw>=0.2.35
Requires-Dist: coincurve>=21.0.0
Requires-Dist: cryptography>=47.0.0
Requires-Dist: deepdiff>=9.0.0
Requires-Dist: dotenv>=0.9.9
Requires-Dist: ehdtd>=0.2.39
Requires-Dist: importlib>=1.0.4
Requires-Dist: orjson>=3.11.8
Requires-Dist: pytz>=2026.1.post1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: statistics>=1.0.3.5
Requires-Dist: ta-lib>=0.6.8
Requires-Dist: thread6>=0.2.0
Requires-Dist: websocket-client>=1.9.0
Description-Content-Type: text/markdown

# CCXAO - CryptoCurrency eXchange Algorithmic Order

CCXAO is a Python library and daemon system for executing algorithmic trading orders across multiple cryptocurrency exchanges. It provides a unified interface for trading on Binance, Bybit, OKX, KuCoin, and BingX with support for limit orders, algorithmic orders with take profit/stop loss, and various utility functions.

## Features

- **Multi-Exchange Support**: Binance, Bybit, OKX, KuCoin, BingX
- **Algorithmic Orders**: Take profit, stop loss, trailing stop functionality
- **Limit Orders**: Optimized for maker fees to reduce trading costs
- **Daemon Architecture**: Client-daemon communication through SQLite database
- **Secure Communication**: HMAC-SHA256 signed commands
- **Balance Management**: Asset conversion and portfolio balancing
- **Market Data**: Real-time prices, order books, exchange information
- **Fee Optimization**: Find symbols with lowest maker fees

## Architecture

The system consists of three main components:

1. **ccxao-daemon**: Background service that manages exchange connections and executes commands
2. **ccxao-cli**: Command-line interface for sending commands to the daemon
3. **CcxaoClient**: Python client library for programmatic access

Communication between components is handled by unix socket

## Installation

### Using Poetry (Recommended)

```bash
# Clone the repository
git clone https://github.com/rmalvarezkai/ccxao
cd ccxao

# Install dependencies
poetry install

# Activate the virtual environment
poetry shell
```

### Using pip

```bash
pip install -e .
```

## Configuration

Create a configuration file at one of these locations:

- `/etc/ccxao-daemon/ccxao-daemon.yaml`
- `~/.ccxao-daemon/ccxao-daemon.yaml`
- `ccxao/.etc/ccxao-daemon.yaml`

### Configuration Example

```yaml
global:
  sandbox: false
  debug: false
  var_dir: .var
  log_dir: .log
  run_dir: .run
  db_name: ccxao_daemon
  ccxao_key: your_secret_key_here
  time_to_purge_algo_orders: 24
  restart_time_limit: 14400

exchanges:
  - exchange: binance
    enabled: true
    api_key: "your_binance_api_key"
    api_secret: "your_binance_api_secret"
    symbols_to_trade:
      - BTC/USDT
      - ETH/USDT

  - exchange: bybit
    enabled: false
    api_key: "your_bybit_api_key"
    api_secret: "your_bybit_api_secret"
    symbols_to_trade:
      - BTC/USDT

  - exchange: okx
    enabled: false
    api_key: "your_okx_api_key"
    api_secret: "your_okx_api_secret"
    api_password: "your_okx_passphrase"
    symbols_to_trade:
      - BTC/USDT
```

### Configuration Parameters

- **ccxao_key**: Secret key for signing commands (generate a random 32-character string)
- **sandbox**: Enable sandbox/testnet mode
- **debug**: Enable debug logging
- **var_dir**: Directory for database and runtime files
- **log_dir**: Directory for log files
- **enabled**: Enable/disable specific exchanges

## Usage

### Starting the Daemon

```bash

# Start daemon in background
ccxao-daemon start

# Start with custom config
ccxao-daemon -c /path/to/config.yaml start

# Check daemon status
ccxao-daemon check

# Stop daemon
ccxao-daemon stop

# Stop with custom config
ccxao-daemon -c /path/to/config.yaml stop

```

### Command Line Interface

#### Basic Commands

```bash
# Ping the daemon
ccxao-cli -c /path/to/config.yaml --exchange=binance ping


# Get account balances
ccxao-cli -c /path/to/config.yaml --exchange=binance get_balances

# Get USDT equivalent balances
ccxao-cli -c /path/to/config.yaml --exchange=binance get_usdt_balances

# Get symbol price
ccxao-cli -c /path/to/config.yaml --exchange=binance get_symbol_price_from_order_book symbol=BTC/USDT res_type=mid

# Get order book
ccxao-cli -c /path/to/config.yaml --exchange=binance get_order_book_for_symbol symbol=BTC/USDT num_result=5

```

#### Order Management

```bash
# Create a limit order
ccxao-cli -c /path/to/config.yaml --exchange=binance create_order order_symbol=BTC/USDT order_side=buy order_amount=0.1 order_price=1.0

# Get order information
ccxao-cli -c /path/to/config.yaml --exchange=binance get_order order_id=ORDER_ID order_symbol=BTC/USDT

# Cancel an order
ccxao-cli -c /path/to/config.yaml --exchange=binance cancel_order order_id=ORDER_ID order_symbol=BTC/USDT

```

#### Algorithmic Orders

```bash
# Queue a bull (long) algorithmic order
ccxao-cli -c /path/to/config.yaml --exchange=binance queue_algo_order order_symbol=BTC/USDT order_amount=0.1 order_price_dir=bull order_price_in=current order_price_tp=0.5% order_price_sl=0.25%

# Queue a bear (short) algorithmic order with trailing stop
ccxao-cli -c /path/to/config.yaml --exchange=binance queue_algo_order order_symbol=BTC/USDT order_amount=0.1 order_price_dir=bear order_price_in=current order_price_tp=0.5% order_price_sl=0.25%

# Check if algorithmic order is finished
ccxao-cli -c /path/to/config.yaml --exchange=binance algo_order_finished order_algo_id=ORDER_ALGO_ID

# List all algorithmic orders
ccxao-cli -c /path/to/config.yaml --exchange=binance get_algo_orders skip_finished=true

```

#### Utility Commands

```bash
# Find symbols with low maker fees
ccxao-cli -c /path/to/config.yaml --exchange=binance get_symbols_with_less_than_fee_maker limit=0.001

# Convert all assets to USDT
ccxao-cli -c /path/to/config.yaml --exchange=binance pass_all_assets_to_asset dest_asset=USDT

# Balance symbol assets (equal USDT value)
ccxao-cli -c /path/to/config.yaml --exchange=binance balance_symbol symbol=BTC/USDT

# Get trading fees
ccxao-cli -c /path/to/config.yaml --exchange=binance get_trading_fees

# Get exchange information
ccxao-cli -c /path/to/config.yaml --exchange=binance get_exchange_info

```

#### Market Information

```bash
# Check if symbol is active
ccxao-cli -c /path/to/config.yaml --exchange=binance is_symbol_active symbol=BTC/USDT

# Get minimum order amount
ccxao-cli -c /path/to/config.yaml --exchange=binance symbol_min_amount symbol=BTC/USDT

# Get minimum order cost
ccxao-cli -c /path/to/config.yaml --exchange=binance symbol_min_cost symbol=BTC/USDT

# Get tick size
ccxao-cli -c /path/to/config.yaml --exchange=binance symbol_tick_size symbol=BTC/USDT

# Round amount to exchange precision
ccxao-cli -c /path/to/config.yaml --exchange=binance amount_to_precision symbol=BTC/USDT order_amount=0.12345678

# Round price to exchange precision
ccxao-cli -c /path/to/config.yaml --exchange=binance price_to_precision symbol=BTC/USDT order_price=1.12345678

```

### Python Client Library

First you have to start a ccxao-daemon

```python
from ccxao.ccxao_client import CcxaoClient

# Initialize client
client = CcxaoClient()

# Get balances
balances = client.get_balances()
print(balances)

# Create a limit order
order = client.create_order(
    exchange='binance',
    order_symbol='BTC/USDT',
    order_side='buy',
    order_amount=0.001,
    order_price=45000
)
print(f"Order created: {order}")

# Queue an algorithmic order
algo_order_id = client.queue_algo_order(
    exchange='binance',
    order_symbol='BTC/USDT',
    order_amount=0.001,
    order_price_dir='bull',
    order_price_in='current',
    order_price_tp='2%',
    order_price_sl='1%'
)
print(f"Algorithmic order queued: {algo_order_id}")

# Get symbol price
price = client.get_symbol_price('binance', 'BTC/USDT')
print(f"BTC/USDT price: {price}")

# Convert all assets to USDT
success = client.pass_all_assets_to_asset(
    'binance',
    'USDT',
    exclude_assets=['BTC', 'ETH']
)
print(f"Asset conversion successful: {success}")
```

### Direct Library Usage (Without Daemon)

```python
from ccxao.ccxao import Ccxao

# Initialize exchange connection
ccxao = Ccxao(
    exchange='binance',
    api_key='your_api_key',
    api_secret='your_api_secret',
    sandbox=False
)

ccxao.start()

# Get balances
balances = ccxao.get_balances()
print(balances)

# Create limit order
order = ccxao.create_order(order_symbol='BTC/USDT', order_side='buy', order_amount=0.001, order_price=45000)
print(order)

# Queue algorithmic order
algo_id = ccxao.queue_algo_order(
    order_symbol='BTC/USDT',
    order_amount=0.001,
    order_price_dir='bull',
    order_price_in='current',
    order_price_tp='2%',
    order_price_sl='1%'
)
print(f"Algo order ID: {algo_id}")

ccxao.stop()
```

## Algorithmic Order Parameters

### Price Direction

- **bull**: Long position (buy low, sell high)
- **bear**: Short position (sell high, buy low)

### Entry Price (order_price_in)

- **current**: Use current market price
- **specific price**: Use exact price value (e.g., 45000)

### Take Profit (order_price_tp)

- **percentage**: e.g., "2%" (2% profit)
- **absolute**: e.g., "46000" (specific price)

### Stop Loss (order_price_sl)

- **percentage**: e.g., "1%" (1% loss)
- **absolute**: e.g., "44000" (specific price)

### Trailing Stop

- **trailing_porc**: Percentage for trailing stop (e.g., 0.5 for 0.5%)
- **trailing_max_steps**: Maximum number of trailing adjustments

## Exchange-Specific Notes

### Binance

- Supports spot
- Requires API key and secret
- Sandbox mode available

### Bybit

- Supports spot
- Requires API key and secret
- Sandbox mode available

### OKX

- Requires API key, secret, and passphrase
- Supports spot
- Sandbox mode available

### KuCoin

- Requires API key, secret, and passphrase
- Supports spot trading
- Sandbox mode available

### BingX

- Requires API key and secret
- Supports spot
- Limited sandbox support

## Security

- All commands are signed using HMAC-SHA256
- API credentials are stored in configuration file
- Database communication is local only
- Supports sandbox/testnet modes for testing

## Logging

Logs are written to the configured log directory:

- `ccxao-daemon.log`: Daemon operations and errors
- `ccxao-client.log`: Client operations and errors

Enable debug logging in configuration for detailed information.

## Error Handling

The system includes comprehensive error handling:

- Invalid signatures are rejected
- Exchange API errors are logged and returned
- Network timeouts are handled gracefully
- Database errors are logged and recovered

## Development

### Code Style

```bash
# Format code
poetry run black ccxao/

# Lint code
poetry run pylint ccxao/

# Type checking
poetry run mypy ccxao/
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For support and questions:

- Create an issue on GitHub
- Check the documentation
- Review the example configurations

## Changelog

### Version 1.0.0

- Initial release
- Multi-exchange support
- Algorithmic order functionality
- Daemon architecture
- CLI interface
- Python client library

## Disclaimer

This software is for educational and research purposes. Cryptocurrency trading involves significant risk. Always test with small amounts and use sandbox modes when available. The authors are not responsible for any financial losses.
