## Core Workflow

### 1. Write a Strategy

## 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

Requires `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in environment.

## Comparing Strategies

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

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")

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.

import vibetrading.live

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

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

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)

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)