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:

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:

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:

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:

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:

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.