Vibetrading

---

name: vibetrading description: "Build, backtest, and deploy cryptocurrency trading strategies using the vibetrading Python framework. Use when: (1) generating trading strategies from natural language, (2) backtesting strategies on historical data, (3) deploying strategies to live exchanges (Hyperliquid, Paradex, Lighter, Aster), (4) comparing strategy performance, (5) working with crypto trading indicators, position sizing, or risk management. NOT for: general finance questions, non-crypto trading, or strategies outside the vibetrading framework."

---

vibetrading

Agent-first crypto trading framework. Strategies are Python functions decorated with @vibe that call sandbox functions (get_perp_price, long, short, etc.). Same code runs in backtest and live.

Install

pip install vibetrading                    # Core
pip install "vibetrading[hyperliquid]"     # + Hyperliquid live trading
pip install "vibetrading[dev]"             # + pytest, ruff

Core Workflow

1. Write a Strategy

import math
from vibetrading import vibe, get_perp_price, get_perp_position, get_perp_summary
from vibetrading import set_leverage, long, reduce_position, get_futures_ohlcv
from vibetrading.indicators import rsi
@vibe(interval="1h")
def my_strategy():
    price = get_perp_price("BTC")
    if math.isnan(price):
        return
    position = get_perp_position("BTC")
    if position and position.get("size", 0) != 0:
        pnl = (price - position["entry_price"]) / position["entry_price"]
        if pnl >= 0.03 or pnl <= -0.02:
            reduce_position("BTC", abs(position["size"]))
        return
    ohlcv = get_futures_ohlcv("BTC", "1h", 20)
    if ohlcv is None or len(ohlcv) < 15:
        return
    if rsi(ohlcv["close"]).iloc[-1] < 30:
        summary = get_perp_summary()
        margin = summary.get("available_margin", 0)
        if margin > 100:
            set_leverage("BTC", 3)
            qty = (margin * 0.1 * 3) / price
            if qty * price >= 15:
                long("BTC", qty, price, order_type="market")

2. Backtest

import vibetrading.backtest
results = vibetrading.backtest.run(code, interval="1h", slippage_bps=5)
m = results["metrics"]
Keys: total_return, sharpe_ratio, sortino_ratio, calmar_ratio, max_drawdown,
       win_rate, profit_factor, expectancy, number_of_trades, cagr, etc.

3. Deploy Live

import vibetrading.live
await vibetrading.live.start(
    code,
    exchange="hyperliquid",
    api_key="0xWalletAddress",
    api_secret="0xPrivateKey",
    interval="1m",
)

Strategy Rules

Every strategy must:

Import and use @vibe or @vibe(interval="1h") decorator

Guard against math.isnan(price) — prices are NaN before data loads

Check position before entering (avoid stacking)

Have both take-profit and stop-loss exits

Check margin > 50 and qty * price >= 15 before trading

Order types: "market" (fills immediately + slippage) or "limit" (fills at price).

Sandbox Functions

Data: get_perp_price(asset), get_spot_price(asset), get_futures_ohlcv(asset, interval, limit), get_spot_ohlcv(asset, interval, limit), get_funding_rate(asset), get_open_interest(asset), get_current_time(), get_supported_assets()

Account: get_perp_summary() → {available_margin, total_margin, ...}, get_perp_position(asset) → {size, entry_price, pnl, leverage} or None, my_spot_balance(asset?), my_futures_balance()

Trading: long(asset, qty, price, order_type="market"), short(asset, qty, price, order_type="market"), buy(asset, qty, price), sell(asset, qty, price), reduce_position(asset, qty), set_leverage(asset, leverage)

Indicators

from vibetrading.indicators import sma, ema, rsi, bbands, atr, macd, stochastic, vwap

All take pandas Series, return pandas Series. Pure pandas — no dependencies.

| Function | Signature | Returns | |---|---|---| | rsi | rsi(close, period=14) | Series (0-100) | | bbands | bbands(close, period=20, std=2.0) | (upper, middle, lower) | | macd | macd(close, fast=12, slow=26, signal=9) | (macd_line, signal, histogram) | | atr | atr(high, low, close, period=14) | Series | | stochastic | stochastic(high, low, close, k=14, d=3) | (%K, %D) |

Position Sizing

from vibetrading.sizing import kelly_size, fixed_fraction_size, volatility_adjusted_size, risk_per_trade_size

kelly_size(win_rate, avg_win, avg_loss, balance, fraction=0.5) — half-Kelly default

risk_per_trade_size(balance, risk_pct, stop_distance, price) — risk-based

Templates

from vibetrading.templates import momentum, mean_reversion, grid, dca, multi_momentum
code = momentum()  # Returns valid strategy code string

AI Generation

import vibetrading.strategy
code = vibetrading.strategy.generate("BTC RSI oversold entry, 3x leverage", model="claude-sonnet-4-20250514")
result = vibetrading.strategy.validate(code)  # Static analysis
report = vibetrading.strategy.analyze(results, strategy_code=code)  # LLM analysis

Requires ANTHROPIC_API_KEY or OPENAI_API_KEY in environment.

Comparing Strategies

import vibetrading.compare
results = vibetrading.compare.run({"RSI": code1, "MACD": code2}, slippage_bps=5)
vibetrading.compare.print_table(results)
df = vibetrading.compare.to_dataframe(results)

Data Download

import vibetrading.tools
from datetime import datetime, timezone
data = vibetrading.tools.download_data(
    ["BTC", "ETH", "SOL"], exchange="binance", interval="1h",
    start_time=datetime(2025, 1, 1, tzinfo=timezone.utc),
    end_time=datetime(2025, 6, 1, tzinfo=timezone.utc),
)
results = vibetrading.backtest.run(code, data=data, slippage_bps=5)

Exchange Credentials

Store in .env.local (gitignored):

| Exchange | api_key | api_secret | Extra | |---|---|---|---| | Hyperliquid | Wallet address 0x... | Private key 0x... | — | | Paradex | StarkNet public key | StarkNet private key | account_address= | | Lighter | API key | API secret | — | | Aster | API key | API secret | user_address= |

Common Patterns

For detailed API docs, strategy patterns, and exchange-specific setup: see references/api-details.md.