Basana runs one crypto strategy against both a backtest exchange and live venues

A framework for strategies that trade crypto, not equities

Basana describes itself as a Python async and event driven framework for algorithmic trading, with a focus on crypto currencies. The focus is not incidental. The project ships dedicated modules for Binance, and the samples directory contains a binance folder, a bitstamp websocket sample and a ccxt_util folder for the CCXT bridge. There is no equity broker integration in the repository listing.

The audience is a developer who already knows what a signal looks like and wants the plumbing handled: an exchange abstraction, an event loop, a backtesting venue that replays history, and websocket feeds for live data. The framework carries only two runtime dependencies, aiohttp with the speedups extra and python-dateutil, which tells you that indicators, dataframe maths and plotting are expected to come from elsewhere.

The project states that its examples are provided for educational purposes only and to be used at your own risk. That sentence is in the README, not in a disclaimer file, and it shapes how you should read the samples below.

One strategy surface, two kinds of exchange

The repository layout shows the central design idea. There is a samples/backtesting folder, a samples/binance folder, and samples that exist in both flavours: backtest_sma.py, backtest_rsi.py, backtest_bbands.py and backtest_pairs_trading.py on one side, binance_bbands.py, binance_websockets.py, ccxt_bbands.py, ccxt_websockets.py and bitstamp_websockets.py on the other, with a samples/strategies folder holding shared logic.

Read from the file names, the same strategy code is exercised against a simulated exchange and against a live venue, with the exchange implementation as the thing that changes. The event driven part is what makes that substitution possible: instead of a script that polls prices in a loop, a strategy receives events and reacts, and the source of those events is swappable between replayed history and a websocket stream.

The samples/core folder appears to hold the shared building blocks, and samples/ccxt_util the helpers for working across venues through CCXT. The distinction between a native Binance module and the CCXT path is a real trade-off: the native module can use exchange specific endpoints, while CCXT gives reach to more than a hundred venues at the price of a common denominator.

Installing Basana with the extras your strategy needs

Installation is a single pip command with optional extras:

$ pip install basana[charts,ccxt]

The extras map to real dependencies in the pyproject metadata. The charts extra brings plotly and kaleido, and the ccxt extra brings ccxt, which is what unlocks the exchange coverage beyond Binance and Bitstamp. Installing without extras leaves you with the core framework and aiohttp.

The examples go further and pull in libraries for the analysis side:

$ pip install talipp pandas statsmodels textual

TALIpp provides the technical indicators, pandas and statsmodels cover the statistical work, and Textual is there for the Binance order book mirror, which draws a live terminal view. The framework itself declares requires-python >=3.10,<4, and the classifiers list Python 3.10 through 3.14.

Two ways to get the code are offered. You can download and unzip a samples archive attached to the 1.11 release, or clone the repository from GitHub. The archive route is the one to use when you want to run the examples without a full checkout.

Feeding the backtest with downloaded bars

The pairs trading example starts by fetching history. The download step is a module invocation with an explicit pair, a period, a start and an end date and an output file:

$ python -m basana.external.binance.tools.download_bars -c BCH/USDT -p 1h -s 2021-12-01 -e 2021-12-26 -o binance_bchusdt_hourly.csv
$ python -m basana.external.binance.tools.download_bars -c CVC/USDT -p 1h -s 2021-12-01 -e 2021-12-26 -o binance_cvcusdt_hourly.csv

One command per market, which is why a pairs strategy needs two of them: BCH/USDT and CVC/USDT over the same window, hourly, written to CSV files the backtest then reads.

With the data on disk, the backtest itself is a module run:

$ python -m samples.backtest_pairs_trading

The CSV route has a practical consequence. The bars are a point in time snapshot downloaded from one exchange, and the backtest has no live feed to fall back on, so what your strategy sees is exactly what the file contains. That is good for reproducibility, and it is also the boundary: the downloaded history is Binance data, so any assumption about fills, spread or liquidity that the file cannot express is not modelled.

The order book mirror shows the event model at full size

The Binance order book mirror is the clearest demonstration of the architecture. The README describes it as maintaining a synchronized local copy of a Binance order book, initializing from a REST API snapshot, then applying real-time diffs from a WebSocket stream, and periodically verifying consistency against fresh snapshots to handle synchronization issues.

That last part is what makes the sample worth reading. A naive mirror applies diffs forever and drifts when a sequence gap appears. The example handles the gap by re-synchronising, and the mirroring code sits in samples/binance/order_book_mirror.py. You run it with:

$ python -m samples.binance_order_book_mirror

The Textual dependency exists for this example, so the terminal view of the book is part of the demonstration rather than an afterthought.

The Binance module is exposed as basana.external.binance, which suggests that exchange adapters live under a stable internal package path. The samples list also includes binance_websockets.py, ccxt_websockets.py and bitstamp_websockets.py, so the websocket pattern is not Binance only, though the documented end to end example is.

Where the framework stops and the trading business starts

Basana is a research and prototyping layer. The README documents a backtesting exchange, exchange connectivity and event plumbing, and it does not document order sizing beyond what a strategy computes, position limits, kill switches, retry policies on failed orders, reconciliation of open orders after a disconnect, or any persistence of state across restarts. None of that is a criticism of the code; it is simply outside what the documentation claims.

The exchange coverage has a similar shape. Binance and Bitstamp are named for live trading, and CCXT integration is described as reaching more than a hundred crypto exchanges. That is reach, not depth: a strategy written against the CCXT interface gets the common subset, and anything exchange specific means returning to a native module.

Other limits come from the dependency set. Because charts are optional and built on plotly with kaleido, a headless deployment without the charts extra has no plotting path. And the samples carry a warning of their own: they are provided for educational purposes only and used at your own risk, which in trading terms means you should never point a sample at an account holding real money before reading what it does with keys and orders.

Release cadence, Python support and the licence question

The release history is unhurried. Version 1.11 was published on 2026-07-22, version 1.10 on 2025-12-27 and version 1.9 on 2025-10-17. The last push to the default branch was on 2026-08-09, and the repository is not archived, so the project is not dormant, but the gap between 1.10 and 1.11 was about seven months and you should plan for a slow upgrade cadence rather than a fast one.

The build uses the uv_build backend and the repository carries a uv.lock file, with a tasks.py file for invoke tasks and ruff configured with a line length of 120. The development group pins pytest, pytest-asyncio, aioresponses for mocking HTTP, mypy, websockets and types-python-dateutil.

On the licence there is a discrepancy you should resolve yourself. The README badge and the pyproject metadata both say Apache-2.0, while the licence identifier on the GitHub repository points to a custom licence that GitHub could not classify, with the LICENSE file in the repository as the authority. That is a licensing fact, not legal advice, and reading the LICENSE file before you depend on the package takes a minute.

Editorial conclusion

Use Basana when your strategy is a Python object that consumes market events and emits orders, you want the same code path exercised against historical bars before real funds are involved, and you are ready to own exchange credentials, risk limits and the operational side of trading. Do not use it for equities, for strategies that need order book level modelling beyond the Binance mirror sample, or as a finished trading product, since the samples are offered for educational purposes only and at your own risk. Before committing, read the LICENSE file yourself, because the pyproject metadata and the README badge say Apache-2.0 while the GitHub licence field points to a custom licence, then run the download_bars command for a pair you know and compare its output against your own data source.

Frequently asked questions

Official sources

1. gbeced/basana on GitHub
2. Issues
3. README
4. Releases