GitHub - borghei/orbiter: Lightweight crypto portfolio optimizer. Efficient frontier, HRP, Risk Parity — with real risk metrics and interactive charts.

Lightweight, open-source crypto portfolio optimizer.
10 optimization strategies, 8 risk metrics, AI-powered views, DeFi yields, sentiment analysis — all from a single CLI or interactive dashboard.

Installation • Who Is This For • Quick Start • Dashboard • Strategies • Features • Python API

Why Orbiter?

Most portfolio optimization tools are built for equities. Crypto is different — 24/7 markets, extreme volatility, fat-tailed returns, and correlations that spike during crashes. Orbiter is built specifically for this.

Fast — Real optimization (not brute-force), results in seconds
Honest — Walk-forward backtesting to avoid overfitting
Practical — CLI for quick analysis, dashboard for exploration, Python API for integration
Comprehensive — From basic mean-variance to regime detection and factor models

Who Is This For

Individual Investors & Traders

You hold multiple crypto assets and want to know the optimal allocation — not just gut feeling, but mathematically optimized weights based on real risk-return tradeoffs. Orbiter tells you exactly how much to put in each coin, shows you the efficient frontier, and validates the strategy with out-of-sample backtesting so you're not just curve-fitting to the past.

What you get:

Run orbiter optimize BTC ETH SOL AVAX and get an allocation in seconds
See how your portfolio would have performed with walk-forward backtesting
Understand your actual risk exposure — max drawdown, CVaR, tail risk
Compare 7 different strategies side-by-side to find what fits your risk tolerance

Quantitative Researchers & Students

You're studying portfolio theory, crypto markets, or quantitative finance and need a clean, well-tested codebase to experiment with. Every module is independent, documented, and covered by tests.

What you get:

Factor model with market, momentum, size, and liquidity factors for crypto
Regime detection (HMM) to study bull/bear/sideways market dynamics
Monte Carlo stress testing with fat-tailed (Student-t) distributions
Efficient frontier computation, correlation analysis, covariance estimation
All code is modular — import just the pieces you need into your own research

Developers & Bot Builders

You're building a trading system, a portfolio dashboard, or an automated rebalancing bot. Orbiter gives you a clean Python API to plug into your stack.

What you get:

pip install orbiter-crypto and import directly — no API keys needed for price data
Programmatic access to all strategies, metrics, and stress tests
Rebalancing simulation with transaction cost modeling (maker/taker fees, slippage)
Calendar, threshold, or hybrid rebalancing triggers
Works with any exchange supported by ccxt (Binance, Bybit, Kraken, OKX, etc.)

Portfolio Managers & Analysts

You manage crypto allocations for clients or a fund and need institutional-grade analytics without paying for Bloomberg PORT.

What you get:

Ledoit-Wolf shrinkage covariance — the same estimator used by institutional quant desks
Risk parity and HRP — strategies used by Bridgewater and other systematic funds
Correlation stress testing — see how your diversification breaks down during crashes
Factor decomposition — understand what's driving your portfolio returns
Interactive Streamlit dashboard for client presentations and exploration

Installation

pip install orbiter-crypto

With the interactive dashboard:

pip install orbiter-crypto[dashboard]

Or install from source:

git clone https://github.com/borghei/orbiter.git
cd orbiter
pip install -e ".[dashboard]"

Quick Start

CLI

# Find the optimal allocation for a portfolio
orbiter optimize BTC ETH SOL AVAX --strategy max-sharpe

# Try different strategies
orbiter optimize BTC ETH SOL AVAX BNB --strategy hrp
orbiter optimize BTC ETH SOL --strategy risk-parity

# Regime-aware: auto-detects bull/bear/sideways and picks the best strategy
orbiter optimize BTC ETH SOL AVAX --strategy regime-aware

# Walk-forward backtest with out-of-sample validation
orbiter backtest BTC ETH SOL AVAX --strategy hrp --train-days 180 --test-days 30

# Stress test your portfolio (Monte Carlo + correlation stress)
orbiter stress BTC ETH SOL AVAX --distribution student-t --horizon 30

# Discover top coins by market cap
orbiter discover --top 30

# Launch the interactive dashboard
orbiter dashboard

Example Output

Strategy: Hierarchical Risk Parity

            Optimal Allocation
┏━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Asset ┃ Weight ┃                       ┃
┡━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│   BTC │  53.3% │ █████████████████████ │
│   ETH │  17.0% │ ██████                │
│   SOL │  15.5% │ ██████                │
│  AVAX │  14.2% │ █████                 │
└───────┴────────┴───────────────────────┘

     Portfolio Metrics
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Metric          ┃  Value ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ Ann. Return     │ -18.8% │
│ Ann. Volatility │  56.7% │
│ Sharpe Ratio    │  -0.33 │
│ Sortino Ratio   │  -0.46 │
│ Max Drawdown    │ -58.4% │
│ Calmar Ratio    │  -0.32 │
│ CVaR (95%)      │ -6.72% │
│ Omega Ratio     │   0.95 │
└─────────────────┴────────┘

Dashboard

Launch with orbiter dashboard and open http://localhost:8501.

The dashboard provides:

Sidebar configuration — pick assets, strategy, covariance method, exchange, lookback period
Allocation pie chart — see how your portfolio is weighted
Metrics overview — Sharpe, return, drawdown, CVaR at a glance
Efficient frontier — interactive scatter plot showing the risk-return tradeoff

Performance chart — cumulative returns vs equal-weight benchmark
Drawdown chart — visualize peak-to-trough declines
Correlation heatmap — understand how your assets move together

Toggle advanced features in the sidebar:

Walk-Forward Backtest — out-of-sample validation with weight history
Stress Testing — Monte Carlo VaR/CVaR + correlation stress
Factor Model — factor loadings heatmap and R-squared per asset

Strategies

Strategy	Description	Best For
`max-sharpe`	Maximize risk-adjusted return (Sharpe ratio)	Aggressive growth
`min-vol`	Minimize portfolio volatility	Capital preservation
`min-cvar`	Minimize tail risk (Conditional Value-at-Risk)	Downside protection
`risk-parity`	Equal risk contribution from each asset	Balanced exposure
`hrp`	Hierarchical Risk Parity — correlation-based, no return estimates	Robust diversification
`regime-aware`	HMM detects bull/bear/sideways, auto-switches strategy	Adaptive allocation
`factor-max-sharpe`	Max Sharpe using factor-model implied returns	Data-driven views
`black-litterman`	Black-Litterman model with investor views (manual or AI-generated)	Subjective + quantitative
`sentiment-regime`	HMM + Fear & Greed, funding rates, exchange flows	Early regime detection
`yield-adjusted`	Max Sharpe with DeFi staking/lending yields factored in	Yield-aware allocation

Features

Risk Metrics

Every optimization returns 8 risk metrics:

Metric	Description
Annualized Return	Geometric mean return, annualized to 365 days
Annualized Volatility	Standard deviation of returns, annualized
Sharpe Ratio	Return per unit of risk
Sortino Ratio	Return per unit of downside risk
Max Drawdown	Largest peak-to-trough decline
Calmar Ratio	Return divided by max drawdown
CVaR (95%)	Expected loss in the worst 5% of scenarios
Omega Ratio	Probability-weighted gains over losses

Covariance Estimation

Method	Description
`ledoit-wolf`	Shrinkage estimator — default, most robust for small samples
`sample`	Standard sample covariance
`exponential`	Exponentially weighted — gives more weight to recent data

Walk-Forward Backtesting

Prevents overfitting by separating training and testing periods:

orbiter backtest BTC ETH SOL AVAX --strategy hrp --train-days 180 --test-days 30

Train on 180 days of data → find optimal weights
Test those weights on the next 30 days (out-of-sample)
Slide forward, repeat
Report aggregated out-of-sample performance vs equal-weight benchmark

Stress Testing

orbiter stress BTC ETH SOL AVAX --distribution student-t --horizon 30 --corr-stress 2.0

Monte Carlo simulation — 10,000 paths with normal or Student-t (fat-tailed) distributions
VaR & CVaR — at 95% and 99% confidence levels
Correlation stress — see how portfolio risk increases when correlations spike (as they do during crashes)

Regime Detection

Hidden Markov Model identifies three market states:

Regime	Characteristics	Strategy Used
Bull	Positive drift, moderate volatility	`max-sharpe`
Sideways	No clear direction, low volatility	`risk-parity`
Bear	Negative drift, high volatility	`min-vol`

orbiter optimize BTC ETH SOL AVAX --strategy regime-aware

Factor Model

Crypto-specific four-factor model:

Market — overall market return (equal or cap-weighted)
Momentum — long recent winners, short recent losers
Size — small-cap minus large-cap returns
Liquidity — high-volume minus low-volume returns

orbiter optimize BTC ETH SOL AVAX --strategy factor-max-sharpe --use-factors

Black-Litterman with AI Views

Combine market equilibrium with your own views — or let AI generate them:

from orbiter import BlackLitterman, View, get_ai
from orbiter.prompts import MARKET_VIEWS_SYSTEM, market_views_prompt
from orbiter.black_litterman import parse_ai_views

# Manual views
views = [
    View(asset="SOL", return_view=0.30, confidence=0.7),
    View(asset=("ETH", "BTC"), return_view=0.05, confidence=0.6),
]
bl = BlackLitterman(returns)
result = bl.optimize(views)

# Or generate views with AI (Claude, OpenAI, or Perplexity)
ai = get_ai("claude")  # reads ANTHROPIC_API_KEY from env
response = ai.generate(MARKET_VIEWS_SYSTEM, market_views_prompt(...))
views = parse_ai_views(response, assets=["BTC", "ETH", "SOL"])
result = bl.optimize(views)

Supports three AI providers with a single middleware:

Provider	Model	Env Variable
Claude	`claude-sonnet-4-20250514`	`ANTHROPIC_API_KEY`
OpenAI	`gpt-4o`	`OPENAI_API_KEY`
Perplexity	`sonar-pro`	`PERPLEXITY_API_KEY`

pip install orbiter-crypto[ai]  # installs anthropic + openai SDKs

Sentiment-Enhanced Regime Detection

Goes beyond price-only HMM by fusing multiple sentiment signals:

Fear & Greed Index — free API, updated daily
Funding rates — crowded leverage detection from perpetual futures
Exchange net flows — coins moving to exchanges = selling pressure

from orbiter import SentimentCollector
from orbiter.regime import SentimentRegimeModel

collector = SentimentCollector(exchange="binance")
sentiment = collector.collect(["BTC", "ETH", "SOL"])

model = SentimentRegimeModel(n_regimes=3)
model.fit(market_returns, sentiment_features_df)
regime = model.current_regime(market_returns, sentiment_features_df)

DeFi Yield-Adjusted Optimization

Staking ETH at 3.5% APY changes the efficient frontier. Orbiter accounts for this:

from orbiter import YieldCollector
from orbiter.defi import adjust_expected_returns

yields = YieldCollector().collect(["ETH", "SOL", "ATOM"])
adjusted_mu = adjust_expected_returns(daily_returns.mean(), yields)

Pulls live yields from DeFiLlama (7000+ protocols)
Falls back to conservative manual estimates if API is down
Includes yield reliability scoring (higher APY = more smart contract risk)

Transaction Cost Modeling

Built-in fee and slippage models for realistic simulations:

Maker/taker exchange fees
Bid-ask spread costs
Almgren-Chriss square-root market impact model

Rebalancing Simulation

Three rebalancing triggers:

Trigger	Description
`calendar`	Rebalance every N days
`threshold`	Rebalance when any weight drifts beyond a threshold
`hybrid`	Threshold check on a calendar schedule

Coin Discovery

orbiter discover --top 20 --min-mcap 1000000000

Fetches top coins from CoinGecko by market cap, with price and volume data.

Python API

Basic Optimization

from orbiter import PriceLoader, PortfolioOptimizer

loader = PriceLoader(exchange="binance")
returns = loader.get_returns(["BTC", "ETH", "SOL", "AVAX"], days=365)

optimizer = PortfolioOptimizer(returns, cov_method="ledoit-wolf")
result = optimizer.optimize("max-sharpe")

print(result.weights)
print(result.metrics)

Efficient Frontier

frontier = optimizer.efficient_frontier(n_points=50)
# DataFrame with columns: return, volatility, sharpe, BTC, ETH, SOL, AVAX

Walk-Forward Backtest

from orbiter.backtest import WalkForwardBacktest

bt = WalkForwardBacktest(returns, train_days=180, test_days=30, strategy="hrp")
result = bt.run()

print(result.metrics)           # Out-of-sample performance
print(result.weights_history)   # Weights at each rebalance

Stress Testing

from orbiter.stress import monte_carlo_stress, correlation_stress

# Monte Carlo with fat tails
mc = monte_carlo_stress(
    weights=result.weights.values,
    mu=returns.mean().values,
    cov=returns.cov().values,
    distribution="student-t",
    df=5.0,
    horizon_days=30,
)
print(mc["cvar_95"], mc["var_99"])

# Correlation stress
cs = correlation_stress(weights, cov_matrix, stress_factor=2.0)
print(cs["stressed_volatility"])

Factor Model

from orbiter.factors import CryptoFactorModel

model = CryptoFactorModel(returns)
exposures = model.fit()

print(exposures.loadings)       # Factor betas per asset
print(exposures.r_squared)      # Model fit per asset
print(model.expected_returns()) # Factor-implied expected returns

Regime Detection

from orbiter.regime import RegimeModel

model = RegimeModel(n_regimes=3)
model.fit(returns["BTC"])

regime = model.current_regime(returns["BTC"])
print(regime)                   # Regime.BULL, Regime.SIDEWAYS, or Regime.BEAR
print(model.get_strategy(regime))

Rebalancing Simulation

from orbiter.rebalance import simulate_rebalancing, RebalanceConfig, RebalanceTrigger
from orbiter.costs import FeeSchedule

config = RebalanceConfig(
    trigger=RebalanceTrigger.THRESHOLD,
    drift_threshold=0.05,
    fee_schedule=FeeSchedule(maker=0.001, taker=0.001),
)
result = simulate_rebalancing(returns, target_weights, config)

print(result.total_turnover)
print(result.total_cost)
print(result.metrics)

Data Sources

Source	Data	API Key
Binance (via ccxt)	OHLCV price data	Not required
Any ccxt exchange	OHLCV price data	Not required
CoinGecko	Market caps, coin discovery	Not required (free tier)
Blockchain.com	BTC active addresses, NVT ratio	Not required

Change the exchange:

orbiter optimize BTC ETH SOL --exchange kraken
orbiter optimize BTC ETH SOL --exchange bybit

CLI Reference

Command	Description
`orbiter optimize SYMBOLS...`	Optimize portfolio allocation
`orbiter backtest SYMBOLS...`	Walk-forward backtest
`orbiter stress SYMBOLS...`	Monte Carlo + correlation stress test
`orbiter discover`	List top coins by market cap
`orbiter dashboard`	Launch Streamlit dashboard

Run orbiter COMMAND --help for full options.

Architecture

src/orbiter/
├── data.py            # Price fetching via ccxt
├── data_sources.py    # CoinGecko, on-chain metrics
├── metrics.py         # Risk & performance metrics
├── covariance.py      # Covariance estimation (sample, Ledoit-Wolf, exponential)
├── optimize.py        # 10 optimization strategies + efficient frontier
├── backtest.py        # Walk-forward backtesting engine
├── costs.py           # Transaction cost & slippage modeling
├── rebalance.py       # Rebalancing simulation (calendar/threshold/hybrid)
├── regime.py          # HMM regime detection + sentiment-enhanced regime
├── stress.py          # Monte Carlo & correlation stress testing
├── factors.py         # Crypto factor model (market, momentum, size, liquidity)
├── black_litterman.py # Black-Litterman model with AI-generated views
├── ai.py              # AI middleware (Claude, OpenAI, Perplexity adapters)
├── prompts.py         # Prompt templates for AI-powered analysis
├── sentiment.py       # Fear & Greed, funding rates, exchange flows
├── defi.py            # DeFi yield data from DeFiLlama
├── cli.py             # Click CLI
└── dashboard.py       # Streamlit interactive dashboard

License

MIT + Commons Clause — Free to use in open-source projects, personal use, education, and internal business workflows. You cannot sell this software or repackage it as a paid product. See LICENSE for full terms.

borghei.me

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
assets		assets
src/orbiter		src/orbiter
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Why Orbiter?

Who Is This For

Individual Investors & Traders

Quantitative Researchers & Students

Developers & Bot Builders

Portfolio Managers & Analysts

Installation

Quick Start

CLI

Example Output

Dashboard

Strategies

Features

Risk Metrics

Covariance Estimation

Walk-Forward Backtesting

Stress Testing

Regime Detection

Factor Model

Black-Litterman with AI Views

Sentiment-Enhanced Regime Detection

DeFi Yield-Adjusted Optimization

Transaction Cost Modeling

Rebalancing Simulation

Coin Discovery

Python API

Basic Optimization

Efficient Frontier

Walk-Forward Backtest

Stress Testing

Factor Model

Regime Detection

Rebalancing Simulation

Data Sources

CLI Reference

Architecture

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages