Spirit is a programmable cryptocurrency trading platform — a playground for building and testing your own trading strategies in Python. It runs on your own hardware, talks to exchanges directly, and you own the strategy logic end-to-end.
The framework is open source under Apache-2.0. Spirit handles the orchestration: market data, order placement, lifecycle hooks, and crash recovery. As your strategies mature, Plus and Pro open up access to our custom technical indicators and cloud storage for backtesting.
On Ubuntu / Debian (and most modern Linux):
sudo apt install -y pipx
pipx ensurepath
pipx install spirit-platformThen open a new shell and run:
python3 -m spirit.setup # interactive setup wizard
spirit --mode paper # start paper tradingOther install paths (venv, etc.) and troubleshooting: see INSTALL.md.
Run the wizard once (it asks your tier, instance name, and an optional Kraken API key for live trading), pick one of the bundled examples (sma_crossover or macd_demo) or drop your own file in ~/.spirit/strategies/, and Spirit starts paper-trading.
To go live, swap --mode paper for --mode live once you've sanity-checked the paper P&L.
OHLC data ownership (v2.2.4+). Spirit's local OHLC store is yours — Free instances persist candles in
~/.spirit/<instance>/spirit.db. When Spirit starts up after downtime, it fills the gap (up to 12 hours of 1-minute candles per boot) from the exchange automatically. For longer gaps, runpython3 -m spirit.backfill <kraken-csv>once with a Kraken CSV export. The boot catch-up adds ~15–20 seconds for a typical multi-pair multi-interval config; configure withSPIRIT_OHLC_CATCHUP_INTERVALS(default60).
See www.tradebot.live/pricing for tier details, pricing, and what each level adds.
Strategies subclass BaseStrategy and implement evaluate_trade(). Everything else is optional; opt into lifecycle hooks as you need them.
from spirit.strategies.base import BaseStrategy
class MyStrategy(BaseStrategy):
def evaluate_trade(self, pair: str, mode: str = "test", **kwargs):
# Return {"entry": bool, "exit": bool, "details": {...}}
return {"entry": False, "exit": False, "details": {}}Optional hooks the orchestrator will call when configured:
on_monitoring_tick, on_entry_confirmed, on_exit_completed,
validate_readiness, get_data_requirements. Properties for tier-aware
behaviour: uses_risk_gate, required_capabilities. See the bundled
examples; both files are heavily commented teaching artifacts:
src/spirit/strategies/examples/sma_crossover.py: minimum viable. Subclass +evaluate_trade, nothing else. Read this first.src/spirit/strategies/examples/macd_demo.py: full lifecycle tour. Multi-interval, monitoring-tick ATR stop, entry-confirmed state-stash, paper-by-default guard. Read this to see every hook in action.
Drop your own under ~/.spirit/strategies/ and Spirit picks it up at next startup.
For more information visit www.tradebot.live.
src/spirit/
main.py - entrypoint
setup.py - first-run wizard
config.py - .env / yaml loader
trade_signal.py - signal dataclass
trade_status.py - status dataclass
trade_types.py - TradeRecord dataclass (used by strategies)
exchange/ - exchange adapter protocol + Kraken impl
pipeline/ - WebSocket event bus, freshness cache, daemon health
storage/ - local SQLite schema (Free tier)
strategies/
base.py - BaseStrategy abstract base class
examples/sma_crossover - minimal reference strategy
examples/macd_demo - full-lifecycle reference strategy
utils/ - data providers, OHLC buffer, paper executor, etc.
The framework runs any strategy you write against any data source you plug in. Plus and Pro plans add bundled indicators served via the gateway API — the D-Limit suite, V3 confidence scorer, and risk-gate calibrators — without changing the framework you're building against. See tradebot.live for what each tier unlocks.
Spirit includes a Kraken adapter by default. You can write your own by implementing the ExchangeProvider protocol in src/spirit/exchange/protocol.py — see docs/reference/EXCHANGE_PLUGIN_GUIDE.md for the full guide.
We'll be releasing more exchange adapters over time. If there's a specific exchange you'd like us to prioritise, open a GitHub issue and we'll see if we can fit it in.
Current release: see the latest tag on PyPI or GitHub Releases for the changelog. The Apache-2.0 framework is stable; Plus and Pro infrastructure is in active development.
Apache-2.0. See LICENSE.
The framework is free to use, modify, and redistribute. Plus and Pro subscriptions cover the hosted data and indicator infrastructure; the framework code itself doesn't depend on a subscription to run.
- Portal + key management: portal.tradebot.live
- Issue tracker: GitHub Issues on this repo
- For commercial / integration questions: support@tradebot.live