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.