MCPInstall

vectorbt

by agiprolabsCode Quality & Workflow

High-performance vectorized backtesting with parameter optimization, portfolio simulation, and rich performance metrics

Installs
498
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/agiprolabs/claude-trading-skills --skill vectorbt
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads vectorbt automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Vectorized Backtesting with vectorbt

Overview

vectorbt is a Python library for vectorized backtesting — running strategy simulations using NumPy/pandas array operations instead of bar-by-bar loops. This makes it 100–1000x faster than event-driven frameworks (backtrader, zipline), enabling parameter optimization across thousands of combinations in seconds.

Key strengths:

  • Blazing speed via NumPy vectorization
  • Built-in parameter grid search and optimization
  • 50+ built-in performance metrics (Sharpe, Sortino, Calmar, max drawdown, profit factor)
  • Rich plotting (equity curves, drawdowns, trade markers, heatmaps)
  • Native pandas integration — your data stays in DataFrames throughout

Installation

uv pip install vectorbt pandas numpy

vectorbt pulls in pandas, NumPy, and Plotly automatically. For technical indicators, also install pandas-ta:

uv pip install vectorbt pandas-ta

Core Concepts

1. Signals — Boolean Entry/Exit Arrays

Strategies in vectorbt are expressed as boolean pandas Series (or arrays) indicating where to enter and exit positions:

import vectorbt as vbt
import pandas as pd

# Entry: buy when fast EMA crosses above slow EMA
entries = fast_ema > slow_ema
# Exit: sell when fast EMA crosses below slow EMA
exits = fast_ema < slow_ema

vectorbt resolves conflicting signals automatically (you can't enter while already in a position).

2. Portfolio — The Backtesting Engine

vbt.Portfolio.from_signals() is the primary backtesting function. It takes price data and entry/exit signals, simulates trades, and computes performance:

pf = vbt.Portfolio.from_signals(
    close=close_prices,
    entries=entries,
    exits=exits,
    init_cash=10_000,
    fees=0.003,       # 0.3% per trade
    slippage=0.005,   # 0.5% slippage
    freq="1h",        # hourly data
)

3. Metrics — Built-in Performance Analysis

# Full stats summary
print(pf.stats())

# Individual metrics
print(f"Total Return: {pf.total_return():.2%}")
print(f"Sharpe Ratio: {pf.sharpe_ratio():.3f}")
print(f"Max Drawdown: {pf.max_drawdown():.2%}")
print(f"Win Rate:     {pf.trades.win_rate():.2%}")

4. Parameter Optimization — Grid Search in Seconds

Pass arrays instead of scalars to test many parameter combos simultaneously:

import numpy as np

fast_periods = np.arange(5, 25, 2)   # 10 values
slow_periods = np.arange(20, 60, 5)  # 8 values

fast_ma = vbt.MA.run(close, fast_periods, short_name="fast")
slow_ma = vbt.MA.run(close, slow_periods, short_name="slow")

# This creates 80 parameter combinations automatically
entries = fast_ma.ma_crossed_above(slow_ma)
exits = fast_ma.ma_crossed_below(slow_ma)

Basic Workflow

Step 1: Load OHLCV Data

import pandas as pd

# From CSV
df = pd.read_csv("ohlcv.csv", parse_dates=["timestamp"], index_col="timestamp")
close = df["close"]

# From Yahoo Finance (traditional markets)
btc = vbt.YFData.download("BTC-USD", start="2023-01-01", end="2025-01-01")
close = btc.get("Close")

For Solana tokens, fetch data via the birdeye-api skill and load into a DataFrame.

Step 2: Compute Indicators

import pandas_ta as ta

# Using pandas-ta (see pandas-ta skill)
df.ta.ema(length=12, append=True)
df.ta.ema(length=26, append=True)
df.ta.rsi(length=14, append=True)
df.ta.bbands(length=20, std=2, append=True)

# Or using vectorbt built-ins
rsi = vbt.RSI.run(close, window=14)
bbands = vbt.BBANDS.run(close, window=20, alpha=2)

Step 3: Generate Entry/Exit Signals

# EMA crossover
entries = df["EMA_12"] > df["EMA_26"]
exits = df["EMA_12"] < df["EMA_26"]

# RSI mean reversion
entries = rsi.rsi_below(30)
exits = rsi.rsi_above(70)

Step 4: Run Backtest

pf = vbt.Portfolio.from_signals(
    close=close,
    entries=entries,
    exits=exits,
    init_cash=10_000,
    fees=0.003,
    slippage=0.005,
    size=0.95,               # use 95% of available cash
    size_type="percent",
    freq="1h",
)

Step 5: Analyze Results

# Summary statistics
print(pf.stats())

# Trade-level analysis
trades = pf.trades.records_readable
print(f"\nTrade count: {len(trades)}")
print(f"Avg holding period: {trades['Duration'].mean()}")

# Equity curve
pf.plot().show()

# Drawdown chart
pf.drawdowns.plot().show()

Key Portfolio Parameters

ParameterDescriptionExample
closePrice series (pd.Series or DataFrame)df["close"]
entriesBoolean entry signalsfast > slow
exitsBoolean exit signalsfast < slow
init_cashStarting capital10_000
feesFee per trade (fraction)0.003 (0.3%)
slippageSlippage per trade (fraction)0.005 (0.5%)
sizePosition size0.95
size_typeHow to interpret size"percent", "amount", "value"
freqData frequency"1h", "4h", "1d"
directionTrade direction"both", "longonly", "shortonly"
accumulateAllow adding to positionsFalse
sl_stopStop-loss level (fraction)0.05 (5%)
tp_stopTake-profit level (fraction)0.10 (10%)

Performance Metrics

Returns

  • total_return() — cumulative return over the period
  • annualized_return() — annualized compound return
  • daily_returns() — Series of daily returns

Risk

  • max_drawdown() — maximum peak-to-trough decline
  • annualized_volatility() — annualized standard deviation of returns
  • value_at_risk() — VaR at specified confidence level

Risk-Adjusted

  • sharpe_ratio() — excess return per unit volatility
  • sortino_ratio() — excess return per unit downside deviation
  • calmar_ratio() — annualized return / max drawdown
  • omega_ratio() — probability-weighted gain/loss ratio

Trade Statistics

  • trades.win_rate() — fraction of profitable trades
  • trades.profit_factor() — gross profit / gross loss
  • trades.expectancy() — average P&L per trade
  • trades.avg_winning_trade() — mean profit on winners
  • trades.avg_losing_trade() — mean loss on losers
  • trades.count() — total number of completed trades

Parameter Optimization

Grid Search

fast_windows = [5, 8, 12, 15, 20]
slow_windows = [20, 26, 30, 40, 50]

# Run all 25 combos at once
fast_ma = vbt.MA.run(close, fast_windows, short_name="fast")
slow_ma = vbt.MA.run(close, slow_windows, short_name="slow")

entries = fast_ma.ma_crossed_above(slow_ma)
exits = fast_ma.ma_crossed_below(slow_ma)

pf = vbt.Portfolio.from_signals(close, entries, exits, fees=0.003)

# Find best params by Sharpe
sharpe = pf.sharpe_ratio()
best_idx = sharpe.idxmax()
print(f"Best params: {best_idx}, Sharpe: {sharpe[best_idx]:.3f}")

Walk-Forward Validation

Always validate optimized parameters on out-of-sample data:

# Split: 70% train, 30% test
split_idx = int(len(close) * 0.7)
train_close = close.iloc[:split_idx]
test_close = close.iloc[split_idx:]

# Optimize on training data
# ... (run grid search on train_close)

# Validate best params on test data
# ... (run single backtest on test_close with best params)

See references/optimization_guide.md for detailed walk-forward methodology and overfitting prevention.

Crypto-Specific Considerations

24/7 Markets

Crypto markets never close. Use hourly or minute-based frequencies, not business-day frequencies:

# Correct for crypto
pf = vbt.Portfolio.from_signals(close, entries, exits, freq="1h")

# Wrong — business days assume market closures
# pf = vbt.Portfolio.from_signals(close, entries, exits, freq="1B")

Realistic Fees

DEX swaps on Solana typically cost 0.25–1% including AMM fees. CEX spot fees are 0.05–0.1%.

# Solana DEX (conservative)
pf = vbt.Portfolio.from_signals(close, entries, exits, fees=0.005)

# CEX spot
pf = vbt.Portfolio.from_signals(close, entries, exits, fees=0.001)

Slippage

Low-liquidity tokens can have 1–5% slippage. Always model this:

# High-liquidity (SOL, ETH): 0.1–0.5%
pf = vbt.Portfolio.from_signals(close, entries, exits, slippage=0.003)

# Low-liquidity memecoins: 1–3%
pf = vbt.Portfolio.from_signals(close, entries, exits, slippage=0.02)

Short History

Many tokens have less than 1 year of data. Be cautious about annualizing metrics from short samples.

Common Strategy Patterns

EMA Crossover

fast = vbt.MA.run(close, 12, short_name="fast")
slow = vbt.MA.run(close, 26, short_name="slow")
entries = fast.ma_crossed_above(slow)
exits = fast.ma_crossed_below(slow)

RSI Mean Reversion

rsi = vbt.RSI.run(close, 14)
entries = rsi.rsi_crossed_below(30)
exits = rsi.rsi_crossed_above(70)

Bollinger Band Breakout

bb = vbt.BBANDS.run(close, window=20, alpha=2)
entries = close > bb.upper
exits = close < bb.lower

Stop-Loss and Take-Profit

pf = vbt.Portfolio.from_signals(
    close, entries, exits,
    sl_stop=0.05,    # 5% stop-loss
    tp_stop=0.10,    # 10% take-profit
)

Related Skills

  • pandas-ta — Technical indicator computation (feeds vectorbt signals)
  • birdeye-api — Fetch Solana token OHLCV data for backtesting
  • trading-visualization — Advanced chart generation for backtest results
  • portfolio-analytics — Deeper portfolio-level risk/return analysis
  • position-sizing — Optimal position sizing methodology
  • risk-management — Portfolio-level risk guardrails
  • regime-detection — Market regime awareness for adaptive strategies

Files

References

  • references/api_guide.md — Complete vectorbt API reference for Portfolio, indicators, plotting, and data loading
  • references/optimization_guide.md — Grid search, walk-forward validation, overfitting prevention, and optimization best practices

Scripts

  • scripts/backtest_example.py — Three-strategy backtest comparison using synthetic data (EMA crossover, RSI mean reversion, Bollinger breakout)
  • scripts/parameter_sweep.py — EMA crossover parameter grid search with walk-forward validation

FAQ

What does the vectorbt skill do?

High-performance vectorized backtesting with parameter optimization, portfolio simulation, and rich performance metrics

How do I install vectorbt?

Run npx skills add https://github.com/agiprolabs/claude-trading-skills --skill vectorbt in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/vectorbt/ (personal) or .claude/skills/vectorbt/ (project).

Which AI agents can use vectorbt?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is vectorbt safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains vectorbt?

It is published by agiprolabs in agiprolabs/claude-trading-skills. It has 498 recorded installs.

More from agiprolabs/claude-trading-skills

View all →

walk-forward-validation

agiprolabs/claude-trading-skills

Walk-forward validation framework for trading strategies and ML models with time-series-aware splits, overfit detection, and regime-aware validation

Business & Finance714 installs

risk-management

agiprolabs/claude-trading-skills

Portfolio-level risk controls, drawdown management, exposure limits, and circuit breakers for crypto trading

Business & Finance637 installs

pandas-ta

agiprolabs/claude-trading-skills

Technical analysis with 130+ indicators using pandas-ta for crypto market data

Data & Databases593 installs

position-sizing

agiprolabs/claude-trading-skills

Trade sizing methods including fixed fractional, volatility-adjusted, Kelly criterion, and liquidity-constrained sizing

Business & Finance581 installs

regime-detection

agiprolabs/claude-trading-skills

Market regime identification using volatility clustering, trend detection, and statistical methods for adaptive trading

Business & Finance578 installs

kelly-criterion

agiprolabs/claude-trading-skills

Kelly criterion optimal sizing with fractional variants, edge estimation, and practical application for crypto trading

Business & Finance534 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs