# Scuriolus
**Scuriolus** is a Rust-based modular trading bot platform designed for automated low-frequency cryptocurrency trading. It supports multiple markets and interchangeable strategies.
By separating the **Market**, **Provider**, and **Strategy** modules, Scuriolus makes it easy to plug in new strategies or exchange adapters. For example, the **Market** component are handled through the **Core** block to manage communication with market APIs and order management, using an embedded database to persist orders and timestamps.
Built-in strategies include a simple benchmark (**StrictBuy** strategy) and a first strategy capturing breakout opportunities.
The project is actively developed with future plans to integrate AI-driven strategies for smarter trading.
## Key Features
- **Modular Architecture**: Separate modules for core logic, markets, and strategies make the codebase extensible. You can easily add new strategies or market connectors by implementing the provided traits.
- **Multiple Markets**: Support for live trading via **MEXC** (using the official Mexc API) and a simulated mode that replays live prices against a local database. This allows development and testing without risking real funds.
- **Pluggable Strategies**: Comes with a `StrictBuy` strategy by default. Additional strategies (e.g. `Trend Tunnel`) can be added by following the example of the included factories. The architecture encourages you to write and plug in custom strategies to maximize gains.
- **Async and High-Performance**: Implemented in Rust with asynchronous Tokio runtime, Scuriolus is performant and safe. Data is persisted using an embedded database (SurrealDB with a RocksDB backend) for reliability.
- **Logging and Configuration**: Uses the `tracing` crate for detailed logging. Log levels are configured with the standard `RUST_LOG` environment variable (for example, `RUST_LOG="debug,mexc_rs=trace" cargo run`). This makes it easy to debug or audit activity.
- **Built-in Tests**: A suite of unit and integration tests is provided (see the `tests/` directory). You can run all tests with Cargo (for example, `cargo test --all --features mexc`). This helps ensure the core functionality remains stable as you develop new features.
## Installation & Getting Started
1. **Clone the repository**:
```bash
git clone https://gitlab.com/LafCorentin/scuriolus.git
cd scuriolus
```
2. **Configure the environment**: Copy the example environment file and fill in any required API keys. In particular, if you want to use the MEXC market, create a .env file from the example:
```bash
cp .env.example .env
# Edit .env to add your Mexc API key/secret if needed
```
(The .env is only required for real trading on MEXC; it can be omitted for offline testing.)
lib.rs
3. **Build and run tests**: Use Cargo (Rust’s package manager) to build and test the project. For example:
```bash
cargo test --all --features mexc
```
This will compile the code and run all tests, including those that require MEXC integration.
> ℹ️ Note for french users : Mexc.com is blocked in France. Use a VPN to access the API.
## Usage
- **Running the Bot**: A command-line interface is included but still under development. Currently, you can run the various binaries directly. For example, to perform a performance benchmark on a strategy, use the provided `perfo` binary:
```bash
cargo run --bin perfo
```
(This example measures a strategy’s performance over historical data.)
> ⚠️ Currently, fees and volumes are not taken into account by the `Simulated` market.
- **Logging Output**: At runtime, Scuriolus outputs logs via the `tracing` framework. Control verbosity with `RUST_LOG` (for example `RUST_LOG=info` or `debug`). This helps in monitoring trading activity or debugging strategy logic.
- **Configuration Options**: You can adjust settings (like log filters, database paths, and strategy parameters) via environment variables or config files as needed. See the source code and documentation comments for all available options.
- **Safety**: The variable `SERIOUS` in the `.env` file brings safety to the project : no real orders will occur as long as it is not set to `TRUE`.
## Architecture and Extending
The codebase is organized into clear modules:
- **Core**: Manages connections to markets, processes orders, and persists data. It tracks all positions and orders placed by your strategies. Can be simulated with past data.
- **Providers**: Modules responsasible to fetch different kind of `Data` from different `Source`, while caching the it. Already available :
- **Mexc** candle lines.
- **Google Trend** search statistics.
- **Strategies**: Implement the `Strategy` trait to define a new trading strategy. Strategy factories generate instances of your algorithm. The existing **StrictBuyFactory** shows how to create a simple strategy that buys on the first tick and sells on exit. The **Trend Tunnel** strategy is a template for a trend-following approach. You are encouraged to implement additional strategies and contribute them back to the project.
## Tests
All core functionality is covered by automated tests. The `tests/` directory contains integration tests for strategies. To run tests, use:
```bash
cargo test --all --features mexc
```
This runs the full suite, including tests that connect to the `Simulated` market. Keeping tests passing is important for ensuring the bot’s reliability.
## Future Work
Planned enhancements include:
- AI-driven strategies: Integrate machine learning or AI components to adapt strategies dynamically.
- More exchanges: Add adapters for additional crypto exchanges or markets.
- More data sources: Implement a generic data storage system to support alternative inputs beyond candlestick data.
- Enhanced CLI and dashboards: Improve the user interface and provide real-time monitoring or web dashboards.
These are areas for collaboration and innovation, so ideas and pull requests are encouraged.
## License
Scuriolus is released under the Apache License 2.0. See the LICENSE file for details.