# Examples
Example applications demonstrating different ways to use the `quantoxide` crate.
## Quick Templates
Direct source code links for quick reference:
| **Trade Operator Templates** | [operators/raw.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/operators/raw.rs) | [signal/mod.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/operators/signal/mod.rs) / [signal/evaluator.rs](https://raw.githubusercontent.com/flemosr/quantoxide/refs/heads/main/examples/operators/signal/evaluator.rs) | - |
| **Synchronization** | [sync_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/sync_tui.rs) | - | [sync_direct.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/sync_direct.rs) |
| **Backtesting** | [backtest_raw_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/backtest_raw_tui.rs) | [backtest_signal_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/backtest_signal_tui.rs) | [backtest_direct.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/backtest_direct.rs) |
| **Parallel Backtesting** | - | - | [backtest_direct_parallel.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/backtest_direct_parallel.rs) |
| **Live Trading** | [live_raw_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/live_raw_tui.rs) | [live_signal_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/live_signal_tui.rs) | [live_direct.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/live_direct.rs) |
| **Carry Trade Operator** | [operators/cross_carry.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/operators/cross_carry.rs) | - | - |
| **Carry Trade Backtesting** | [backtest_cross_carry_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/backtest_cross_carry_tui.rs) | - | [backtest_cross_carry.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/backtest_cross_carry.rs) |
| **Live Carry Trading** | [live_cross_carry_tui.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/live_cross_carry_tui.rs) | - | - |
Utilities shared across examples:
- [util/input.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/util/input.rs) - CLI argument parsing and date handling
- [util/metrics.rs](https://raw.githubusercontent.com/flemosr/quantoxide/main/examples/util/metrics.rs) - Financial metrics (Sharpe ratio, max drawdown)
## Prerequisites
All examples require a local database URL in `DATABASE_URL`.
Supported database URLs:
- `sqlite:./path/to/quantoxide.sqlite` - SQLite database file. This is the simplest local backend;
the path after `sqlite:` is resolved relative to the directory where the example command is run,
and the file is created automatically when the `sqlite` feature is enabled.
- `postgres://postgres:password@localhost:5432/postgres` - PostgreSQL connection URL.
`Database::new` automatically runs the matching backend migrations on first use.
Synchronization examples use the `lnm-sdk` default LN Markets REST/Stream endpoints.
Live trading examples require:
- `LNM_API_KEY` - The LN Markets API v3 key
- `LNM_API_SECRET` - The LN Markets API v3 secret
- `LNM_API_PASSPHRASE` - The LN Markets API v3 passphrase
Recommended live API key permissions:
+ `account:read` to view account balance
+ `futures:isolated:read` to view isolated margin positions
+ `futures:isolated:write` to create and manage isolated positions
+ `futures:cross:read` to view the cross margin position
+ `futures:cross:write` to manage the cross margin position
These environment variables should be set, or a `.env` file should be added in the project root.
A [`.env.template`](https://github.com/flemosr/quantoxide/blob/main/.env.template) file is
available.
### Setting up SQLite
For local development, create a `.env` file with:
```env
DATABASE_URL=sqlite:./target/quantoxide.sqlite
```
With this value, running examples from the repository root creates `./target/quantoxide.sqlite`,
keeping the generated database under Cargo's ignored build directory. Then run examples with the
SQLite feature, for example:
```bash
cargo run --no-default-features --features sqlite --example sync_tui
```
### Setting up PostgreSQL with Docker
To quickly set up a PostgreSQL database for running the examples with the default feature:
```bash
docker run -d \
--name quantoxide-postgres \
-e POSTGRES_PASSWORD=password \
-p 5432:5432 \
-v quantoxide-pgdata:/var/lib/postgresql \
postgres:18.4-bookworm
```
Then `DATABASE_URL` should be set to:
```env
DATABASE_URL=postgres://postgres:password@localhost:5432/postgres
```
Useful commands:
+ Stop the container: `docker stop quantoxide-postgres`
+ Start the container: `docker start quantoxide-postgres`
+ Remove the container: `docker rm quantoxide-postgres`
+ Remove the persistent volume: `docker volume rm quantoxide-pgdata`
## Synchronization
The following examples demonstrate the synchronization engine, which is responsible for determining
the current state of the data stored in the local database, identifying gaps, and fetching the
necessary data from the LN Markets API to remediate them.
### sync_tui
Demonstrates how to run the sync process using its TUI (Terminal User Interface) abstraction, that
automatically handles and displays updates. This is the **recommended approach** for most use cases.
Usage:
```bash
cargo run --example sync_tui
```
### sync_direct
Demonstrates direct interaction with the sync process for custom update handling. This approach is
more LLM-friendly, and simplifies integration of sync updates into other UIs or processing logic.
Usage:
```bash
cargo run --example sync_direct
```
## Backtesting
The following examples demonstrate the backtesting engine, which allows testing trading strategies
against historical data stored in the local database. **Some price history must be available in the
local database to run the backtest examples**. It can be obtained by running one of the
synchronization examples.
### backtest_raw_tui / backtest_signal_tui
Demonstrates how to run the backtest process using its TUI (Terminal User Interface) abstraction,
that automatically handles and displays updates. This is the **recommended approach** for most use
cases.
Usage with a **raw operator**:
```bash
cargo run --example backtest_raw_tui
```
Usage with a **signal operator** and evaluators:
```bash
cargo run --example backtest_signal_tui
```
### backtest_direct
Demonstrates direct interaction with the backtest process for custom update handling. This approach
is more LLM-friendly, and simplifies integration of backtest updates into other UIs or processing
logic.
Usage:
```bash
cargo run --example backtest_direct -- --start <DATE> --end <DATE> [OPTIONS]
```
Required:
- `--start <DATE>` - Start date in YYYY-MM-DD format
- `--end <DATE>` - End date in YYYY-MM-DD format
Options:
- `--balance <SATS>` - Starting balance in sats (default: 10000000)
- `--rfr-sats <RATE>` - Annual risk-free rate for sats as decimal (default: 0.0)
- `--rfr-usd <RATE>` - Annual risk-free rate for USD as decimal (default: 0.0)
Example:
```bash
cargo run --example backtest_direct -- --start 2025-09-01 --end 2025-12-01 --balance 10000000 --rfr-sats 0.0 --rfr-usd 0.05
```
### backtest_direct_parallel
Demonstrates direct interaction with the parallel backtest engine for custom update handling. This
approach is more LLM-friendly, and simplifies integration of parallel backtest updates into other
UIs or processing logic.
The parallel backtest engine allows multiple operators to be run in parallel over the same time
period and starting balance, while maintaining isolated trade execution state per operator. Candle
management overhead is shared across all operators, making this significantly more efficient than
running separate backtests. Useful for comparing strategies or running parameter sweeps.
Usage:
```bash
cargo run --example backtest_direct_parallel -- --start <DATE> --end <DATE> [OPTIONS]
```
Required:
- `--start <DATE>` - Start date in YYYY-MM-DD format
- `--end <DATE>` - End date in YYYY-MM-DD format
Options:
- `--balance <SATS>` - Starting balance in sats (default: 10000000)
- `--rfr-sats <RATE>` - Annual risk-free rate for sats as decimal (default: 0.0)
- `--rfr-usd <RATE>` - Annual risk-free rate for USD as decimal (default: 0.0)
Example:
```bash
cargo run --example backtest_direct_parallel -- --start 2025-09-01 --end 2025-12-01 --balance 10000000 --rfr-sats 0.0 --rfr-usd 0.05
```
## Live Trading
The following examples demonstrate the live trading engine, which executes trading strategies in
real-time against the LN Markets API using live market data and real trading operations.
### live_raw_tui / live_signal_tui
Demonstrates how to run the live trading process using its TUI (Terminal User Interface) abstraction,
that automatically handles and displays updates. This is the **recommended approach** for most use
cases.
Usage with a **raw operator**:
```bash
cargo run --example live_raw_tui
```
Usage with a **signal operator** and evaluators:
```bash
cargo run --example live_signal_tui
```
### live_direct
Demonstrates direct interaction with the live trading process for custom update handling. This
approach is more LLM-friendly, and simplifies integration of live trading updates into other UIs or
processing logic.
Usage:
```bash
cargo run --example live_direct
```
## Carry Trading
These examples demonstrate cross-margin trades applied to a carry-trade strategy. The strategy
receives a target hedge percentage as a parameter, keeps a short cross-margin hedge sized to that
percentage of account NAV, rebalances when hedge drift exceeds the configured threshold, and
adjusts cross collateral to maintain the configured liquidation buffer. Positive funding rates pay
shorts. Funding settlements are reflected in cross margin and therefore in the account net value
used as the hedge target.
### backtest_cross_carry_tui / backtest_cross_carry
Runs the carry-trade strategy through the backtesting engine with simulated cross-margin trades.
Usage with the **TUI**:
```bash
cargo run --example backtest_cross_carry_tui
```
Usage without the TUI:
```bash
cargo run --example backtest_cross_carry -- --start <DATE> --end <DATE> [OPTIONS]
```
The TUI variant prompts for start date, starting balance, hedge percentage, and end date before
launching the terminal interface.
The direct variant accepts the following arguments.
Required:
- `--start <DATE>` - Start date in YYYY-MM-DD format
- `--end <DATE>` - End date in YYYY-MM-DD format
Options:
- `--balance <SATS>` - Starting balance in sats (default: 10000000)
- `--hedge-perc <PCT>` - Target hedge percentage of account NAV (default: 100)
Example:
```bash
cargo run --example backtest_cross_carry -- --start 2025-09-01 --end 2025-12-01 --balance 10000000 --hedge-perc 100
```
### live_cross_carry_tui
Runs the same carry-trade strategy against the live LN Markets account with the TUI. It requires
the recommended live API key permissions above, including `futures:cross:read` and
`futures:cross:write`.
**Warning:** this example results in real cross-margin exposure. Backtest the same operator with
`backtest_cross_carry_tui` first and review your account state before running it live.
Usage:
```bash
cargo run --example live_cross_carry_tui
```