Vibetrading

SKILL.md

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

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

## Core Workflow

### 1. Write a Strategy

```python
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

```python
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

```python
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

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

## AI Generation

```python
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

```python
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

```python
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](references/api-details.md).