@hummingbot/skills 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# Hummingbot Skills
+
+AI agent skills for [Hummingbot](https://hummingbot.org) algorithmic trading infrastructure.
+
+Built on the [Agent Skills](https://agentskills.io) open standard.
+
+## Installation
+
+```bash
+npx skills add hummingbot/skills
+```
+
+Or install a specific skill:
+```bash
+npx skills add hummingbot/skills --skill executor-creator
+```
+
+## Usage
+
+After installing, ask your AI agent:
+
+- "Create a BTC position with 2% stop loss and 4% take profit"
+- "Show me the RSI for ETH on Binance"
+- "Add my Binance API keys"
+- "Set up Hummingbot with Docker"
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| [hummingbot-api-setup](./skills/hummingbot-api-setup/) | Deploy Hummingbot infrastructure (Docker, API, Gateway) |
+| [keys-manager](./skills/keys-manager/) | Manage exchange API credentials |
+| [executor-creator](./skills/executor-creator/) | Create trading executors (position, grid, DCA, TWAP) |
+| [candles-feed](./skills/candles-feed/) | Fetch market data and technical indicators |
+
+## Prerequisites
+
+Skills interact with the Hummingbot API server:
+- **URL**: `http://localhost:8000`
+- **Credentials**: `admin:admin`
+- **Docs**: `http://localhost:8000/docs`
+
+Use the `hummingbot-api-setup` skill to deploy the API server.
+
+## Repository Structure
+
+```
+hummingbot/skills/
+├── skills/                     # Skill definitions
+│   ├── hummingbot-api-setup/   # Infrastructure setup
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   ├── keys-manager/           # API credentials
+│   ├── executor-creator/       # Trading executors
+│   └── candles-feed/           # Market data
+└── skills.json                 # Skill metadata (for webapp)
+```
+
+## Links
+
+- [Hummingbot](https://hummingbot.org)
+- [skills.sh](https://skills.sh)
+- [Agent Skills Spec](https://agentskills.io)

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hummingbot/skills",
+  "version": "1.0.0",
+  "description": "AI agent skills for Hummingbot algorithmic trading infrastructure",
+  "keywords": [
+    "hummingbot",
+    "trading",
+    "crypto",
+    "ai-agent",
+    "skills",
+    "algorithmic-trading"
+  ],
+  "homepage": "https://skills.hummingbot.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hummingbot/skills.git"
+  },
+  "license": "Apache-2.0",
+  "author": "Hummingbot Foundation <dev@hummingbot.org>",
+  "files": [
+    "skills/",
+    "skills.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/candles-feed/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: candles-feed
+description: Fetch market data (OHLCV candles) and calculate technical indicators (RSI, EMA, MACD, Bollinger Bands) from exchanges via Hummingbot API. Use this skill when the user needs price data, candlestick charts, or technical analysis.
+license: Apache-2.0
+---
+
+# Hummingbot Candles Skill
+
+This skill fetches candlestick (OHLCV) data from exchanges and calculates technical indicators. It provides the data foundation for strategy development and market analysis.
+
+## Prerequisites
+
+- Hummingbot API server must be running (use the setup skill)
+- Exchange connector must support candle data
+
+## Capabilities
+
+### 1. Get Available Connectors
+
+List exchanges that support candle data:
+
+```bash
+./scripts/list_candle_connectors.sh
+```
+
+### 2. Fetch Candles
+
+Get OHLCV data for a trading pair:
+
+```bash
+./scripts/get_candles.sh \
+    --connector binance \
+    --pair BTC-USDT \
+    --interval 1h \
+    --days 30
+```
+
+Supported intervals: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w`
+
+### 3. Calculate Indicators
+
+Calculate technical indicators on candle data:
+
+```bash
+# RSI (Relative Strength Index)
+./scripts/calculate_indicator.sh \
+    --connector binance \
+    --pair BTC-USDT \
+    --indicator rsi \
+    --period 14
+
+# EMA (Exponential Moving Average)
+./scripts/calculate_indicator.sh \
+    --connector binance \
+    --pair BTC-USDT \
+    --indicator ema \
+    --period 20
+
+# MACD (Moving Average Convergence Divergence)
+./scripts/calculate_indicator.sh \
+    --connector binance \
+    --pair BTC-USDT \
+    --indicator macd \
+    --fast 12 \
+    --slow 26 \
+    --signal 9
+
+# Bollinger Bands
+./scripts/calculate_indicator.sh \
+    --connector binance \
+    --pair BTC-USDT \
+    --indicator bb \
+    --period 20 \
+    --std 2
+```
+
+### 4. Get Current Price
+
+Get the latest price for trading pairs:
+
+```bash
+./scripts/get_price.sh \
+    --connector binance \
+    --pairs "BTC-USDT,ETH-USDT"
+```
+
+### 5. Get Funding Rate (Perpetuals)
+
+Get funding rate for perpetual contracts:
+
+```bash
+./scripts/get_funding_rate.sh \
+    --connector binance_perpetual \
+    --pair BTC-USDT
+```
+
+## Supported Indicators
+
+| Indicator | Code | Parameters | Description |
+|-----------|------|------------|-------------|
+| RSI | `rsi` | period | Relative Strength Index |
+| EMA | `ema` | period | Exponential Moving Average |
+| SMA | `sma` | period | Simple Moving Average |
+| MACD | `macd` | fast, slow, signal | Moving Average Convergence Divergence |
+| Bollinger Bands | `bb` | period, std | Volatility bands |
+| ATR | `atr` | period | Average True Range |
+| VWAP | `vwap` | - | Volume Weighted Average Price |
+| Stochastic | `stoch` | k_period, d_period | Stochastic Oscillator |
+
+## Candle Data Format
+
+Returned candle data includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | int | Unix timestamp (ms) |
+| `open` | float | Opening price |
+| `high` | float | Highest price |
+| `low` | float | Lowest price |
+| `close` | float | Closing price |
+| `volume` | float | Trading volume |
+
+Example output:
+```json
+{
+    "candles": [
+        {
+            "timestamp": 1706400000000,
+            "open": 42150.5,
+            "high": 42300.0,
+            "low": 42100.0,
+            "close": 42250.0,
+            "volume": 1250.5
+        }
+    ],
+    "interval": "1h",
+    "total_candles": 720
+}
+```
+
+## Indicator Output
+
+### RSI Output
+```json
+{
+    "indicator": "rsi",
+    "period": 14,
+    "current_value": 65.5,
+    "signal": "neutral",
+    "interpretation": {
+        "overbought": 70,
+        "oversold": 30,
+        "description": "RSI at 65.5 indicates slightly bullish momentum"
+    }
+}
+```
+
+### MACD Output
+```json
+{
+    "indicator": "macd",
+    "current_values": {
+        "macd_line": 125.5,
+        "signal_line": 110.2,
+        "histogram": 15.3
+    },
+    "signal": "bullish",
+    "interpretation": "MACD above signal line, positive momentum"
+}
+```
+
+### Bollinger Bands Output
+```json
+{
+    "indicator": "bb",
+    "period": 20,
+    "std": 2,
+    "current_values": {
+        "upper": 43500.0,
+        "middle": 42000.0,
+        "lower": 40500.0,
+        "current_price": 42250.0
+    },
+    "position": "middle",
+    "bandwidth": 0.071
+}
+```
+
+## Workflow: Market Analysis
+
+1. **Check available connectors**
+   ```bash
+   ./scripts/list_candle_connectors.sh
+   ```
+
+2. **Fetch candle data**
+   ```bash
+   ./scripts/get_candles.sh --connector binance --pair BTC-USDT --interval 4h --days 30
+   ```
+
+3. **Calculate indicators**
+   ```bash
+   # Get RSI
+   ./scripts/calculate_indicator.sh --connector binance --pair BTC-USDT --indicator rsi --period 14
+
+   # Get EMA crossover
+   ./scripts/calculate_indicator.sh --connector binance --pair BTC-USDT --indicator ema --period 20
+   ./scripts/calculate_indicator.sh --connector binance --pair BTC-USDT --indicator ema --period 50
+   ```
+
+4. **Interpret signals**
+   - RSI > 70: Overbought, potential sell signal
+   - RSI < 30: Oversold, potential buy signal
+   - EMA(20) > EMA(50): Bullish trend
+   - EMA(20) < EMA(50): Bearish trend
+
+## API Endpoints Used
+
+All requests go to `http://localhost:8000` with Basic Auth (`admin:admin`):
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/market-data/available-candle-connectors` | GET | List connectors with candle support |
+| `/market-data/historical-candles` | POST | Fetch bulk historical OHLCV data |
+| `/market-data/candles` | POST | Fetch real-time OHLCV data |
+| `/market-data/prices` | POST | Get current prices |
+| `/market-data/funding-info` | POST | Get funding rates |
+
+## Data Fetching Strategy
+
+Scripts use a dual-fetch approach for comprehensive data:
+1. **Historical candles** - Bulk data from `/market-data/historical-candles`
+2. **Real-time candles** - Latest data from `/market-data/candles`
+3. **Merge** - Deduplicate by timestamp, real-time overrides historical
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_URL` | `http://localhost:8000` | API base URL |
+| `API_USER` | `admin` | API username |
+| `API_PASS` | `admin` | API password |
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Connector not supported" | Exchange doesn't support candles | Use list_candle_connectors |
+| "Invalid interval" | Unsupported interval format | Use 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w |
+| "Rate limited" | Too many requests | Wait and retry |
+| "Invalid trading pair" | Pair not available | Check exchange for valid pairs |
+
+## Notes
+
+- Candle data is fetched directly from exchanges via the Hummingbot API
+- Indicators are calculated locally using the fetched candle data
+- Historical data availability varies by exchange (typically 30-90 days)
+- For real-time data, consider shorter intervals (1m, 5m)
+- For trend analysis, use longer intervals (4h, 1d)

package/skills/candles-feed/scripts/calculate_indicator.sh

@@ -0,0 +1,359 @@
+#!/bin/bash
+# Calculate technical indicators on candle data
+# Usage: ./calculate_indicator.sh --connector CONNECTOR --pair PAIR --indicator INDICATOR [--period PERIOD] [options]
+
+set -e
+
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+CONNECTOR=""
+TRADING_PAIR=""
+INDICATOR=""
+PERIOD=14
+INTERVAL="1h"
+DAYS=30
+# MACD specific
+FAST=12
+SLOW=26
+SIGNAL=9
+# BB specific
+STD=2
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --connector)
+            CONNECTOR="$2"
+            shift 2
+            ;;
+        --pair)
+            TRADING_PAIR="$2"
+            shift 2
+            ;;
+        --indicator)
+            INDICATOR="$2"
+            shift 2
+            ;;
+        --period)
+            PERIOD="$2"
+            shift 2
+            ;;
+        --interval)
+            INTERVAL="$2"
+            shift 2
+            ;;
+        --days)
+            DAYS="$2"
+            shift 2
+            ;;
+        --fast)
+            FAST="$2"
+            shift 2
+            ;;
+        --slow)
+            SLOW="$2"
+            shift 2
+            ;;
+        --signal)
+            SIGNAL="$2"
+            shift 2
+            ;;
+        --std)
+            STD="$2"
+            shift 2
+            ;;
+        --api-url)
+            API_URL="$2"
+            shift 2
+            ;;
+        --api-user)
+            API_USER="$2"
+            shift 2
+            ;;
+        --api-pass)
+            API_PASS="$2"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Validate required arguments
+if [ -z "$CONNECTOR" ]; then
+    echo '{"error": "connector is required. Use --connector CONNECTOR_NAME"}'
+    exit 1
+fi
+
+if [ -z "$TRADING_PAIR" ]; then
+    echo '{"error": "trading pair is required. Use --pair TRADING_PAIR"}'
+    exit 1
+fi
+
+if [ -z "$INDICATOR" ]; then
+    echo '{"error": "indicator is required. Use --indicator [rsi|ema|sma|macd|bb|atr]"}'
+    exit 1
+fi
+
+# Calculate max records needed
+case "$INTERVAL" in
+    *m)
+        MINUTES=${INTERVAL%m}
+        MAX_RECORDS=$((1440 * DAYS / MINUTES))
+        ;;
+    *h)
+        HOURS=${INTERVAL%h}
+        MAX_RECORDS=$((24 * DAYS / HOURS))
+        ;;
+    *d)
+        MAX_RECORDS=$DAYS
+        ;;
+    *)
+        MAX_RECORDS=$((24 * DAYS))
+        ;;
+esac
+
+# Calculate timestamps for historical fetch
+END_TIME=$(date +%s)
+START_TIME=$((END_TIME - DAYS * 24 * 3600))
+
+# Fetch historical candles
+HISTORICAL=$(curl -s -u "$API_USER:$API_PASS" \
+    -X POST "$API_URL/market-data/historical-candles" \
+    -H "Content-Type: application/json" \
+    -d "{\"connector_name\": \"$CONNECTOR\", \"trading_pair\": \"$TRADING_PAIR\", \"interval\": \"$INTERVAL\", \"start_time\": $START_TIME, \"end_time\": $END_TIME}" 2>/dev/null || echo "[]")
+
+# Fetch real-time candles
+REALTIME=$(curl -s -u "$API_USER:$API_PASS" \
+    -X POST "$API_URL/market-data/candles" \
+    -H "Content-Type: application/json" \
+    -d "{\"connector_name\": \"$CONNECTOR\", \"trading_pair\": \"$TRADING_PAIR\", \"interval\": \"$INTERVAL\", \"max_records\": 100}" 2>/dev/null || echo "[]")
+
+# Merge and deduplicate by timestamp
+CANDLES=$(echo "$HISTORICAL $REALTIME" | jq -s '.[0] + .[1] | group_by(.timestamp) | map(.[0]) | sort_by(.timestamp)')
+
+if echo "$CANDLES" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to fetch candles\", \"detail\": $CANDLES}"
+    exit 1
+fi
+
+# Extract close prices (compact JSON to avoid newline issues in heredoc)
+CLOSES=$(echo "$CANDLES" | jq -c '[.[].close]')
+HIGHS=$(echo "$CANDLES" | jq -c '[.[].high]')
+LOWS=$(echo "$CANDLES" | jq -c '[.[].low]')
+VOLUMES=$(echo "$CANDLES" | jq -c '[.[].volume]')
+TOTAL=$(echo "$CANDLES" | jq 'length')
+
+# Calculate indicator using Python (for accurate calculations)
+calculate_with_python() {
+    python3 << PYTHON_SCRIPT
+import json
+import sys
+
+closes = json.loads('$CLOSES')
+highs = json.loads('$HIGHS')
+lows = json.loads('$LOWS')
+volumes = json.loads('$VOLUMES')
+indicator = '$INDICATOR'
+period = int('$PERIOD')
+fast = int('$FAST')
+slow = int('$SLOW')
+signal_period = int('$SIGNAL')
+std_dev = float('$STD')
+
+def sma(data, period):
+    if len(data) < period:
+        return None
+    return sum(data[-period:]) / period
+
+def ema(data, period):
+    if len(data) < period:
+        return None
+    multiplier = 2 / (period + 1)
+    ema_val = sum(data[:period]) / period
+    for price in data[period:]:
+        ema_val = (price - ema_val) * multiplier + ema_val
+    return ema_val
+
+def rsi(data, period):
+    if len(data) < period + 1:
+        return None
+    gains = []
+    losses = []
+    for i in range(1, len(data)):
+        change = data[i] - data[i-1]
+        if change > 0:
+            gains.append(change)
+            losses.append(0)
+        else:
+            gains.append(0)
+            losses.append(abs(change))
+
+    avg_gain = sum(gains[-period:]) / period
+    avg_loss = sum(losses[-period:]) / period
+
+    if avg_loss == 0:
+        return 100
+    rs = avg_gain / avg_loss
+    return 100 - (100 / (1 + rs))
+
+def macd(data, fast_period, slow_period, signal_period):
+    if len(data) < slow_period:
+        return None, None, None
+    fast_ema = ema(data, fast_period)
+    slow_ema = ema(data, slow_period)
+    macd_line = fast_ema - slow_ema
+
+    # Calculate signal line (EMA of MACD)
+    macd_values = []
+    for i in range(slow_period, len(data)):
+        subset = data[:i+1]
+        f = ema(subset, fast_period)
+        s = ema(subset, slow_period)
+        macd_values.append(f - s)
+
+    signal_line = ema(macd_values, signal_period) if len(macd_values) >= signal_period else macd_line
+    histogram = macd_line - signal_line
+
+    return macd_line, signal_line, histogram
+
+def bollinger_bands(data, period, std_multiplier):
+    if len(data) < period:
+        return None, None, None
+    middle = sma(data, period)
+    variance = sum((x - middle) ** 2 for x in data[-period:]) / period
+    std = variance ** 0.5
+    upper = middle + (std_multiplier * std)
+    lower = middle - (std_multiplier * std)
+    return upper, middle, lower
+
+def atr(highs, lows, closes, period):
+    if len(closes) < period + 1:
+        return None
+    tr_values = []
+    for i in range(1, len(closes)):
+        hl = highs[i] - lows[i]
+        hc = abs(highs[i] - closes[i-1])
+        lc = abs(lows[i] - closes[i-1])
+        tr_values.append(max(hl, hc, lc))
+    return sum(tr_values[-period:]) / period
+
+result = {}
+current_price = closes[-1] if closes else 0
+
+if indicator == 'rsi':
+    value = rsi(closes, period)
+    if value is not None:
+        if value > 70:
+            sig = 'overbought'
+        elif value < 30:
+            sig = 'oversold'
+        else:
+            sig = 'neutral'
+        result = {
+            'indicator': 'rsi',
+            'period': period,
+            'current_value': round(value, 2),
+            'signal': sig,
+            'interpretation': {
+                'overbought_threshold': 70,
+                'oversold_threshold': 30,
+                'description': f'RSI at {round(value, 2)} indicates {sig} conditions'
+            }
+        }
+
+elif indicator == 'ema':
+    value = ema(closes, period)
+    if value is not None:
+        trend = 'bullish' if current_price > value else 'bearish'
+        result = {
+            'indicator': 'ema',
+            'period': period,
+            'current_value': round(value, 2),
+            'current_price': round(current_price, 2),
+            'signal': trend,
+            'distance_pct': round((current_price - value) / value * 100, 2)
+        }
+
+elif indicator == 'sma':
+    value = sma(closes, period)
+    if value is not None:
+        trend = 'bullish' if current_price > value else 'bearish'
+        result = {
+            'indicator': 'sma',
+            'period': period,
+            'current_value': round(value, 2),
+            'current_price': round(current_price, 2),
+            'signal': trend,
+            'distance_pct': round((current_price - value) / value * 100, 2)
+        }
+
+elif indicator == 'macd':
+    macd_line, signal_line, histogram = macd(closes, fast, slow, signal_period)
+    if macd_line is not None:
+        sig = 'bullish' if histogram > 0 else 'bearish'
+        result = {
+            'indicator': 'macd',
+            'parameters': {'fast': fast, 'slow': slow, 'signal': signal_period},
+            'current_values': {
+                'macd_line': round(macd_line, 4),
+                'signal_line': round(signal_line, 4),
+                'histogram': round(histogram, 4)
+            },
+            'signal': sig,
+            'interpretation': f'MACD {"above" if histogram > 0 else "below"} signal line, {sig} momentum'
+        }
+
+elif indicator == 'bb':
+    upper, middle, lower = bollinger_bands(closes, period, std_dev)
+    if upper is not None:
+        bandwidth = (upper - lower) / middle
+        if current_price > upper:
+            position = 'above_upper'
+        elif current_price < lower:
+            position = 'below_lower'
+        else:
+            position = 'middle'
+        result = {
+            'indicator': 'bb',
+            'period': period,
+            'std': std_dev,
+            'current_values': {
+                'upper': round(upper, 2),
+                'middle': round(middle, 2),
+                'lower': round(lower, 2),
+                'current_price': round(current_price, 2)
+            },
+            'position': position,
+            'bandwidth': round(bandwidth, 4)
+        }
+
+elif indicator == 'atr':
+    value = atr(highs, lows, closes, period)
+    if value is not None:
+        atr_pct = (value / current_price) * 100
+        result = {
+            'indicator': 'atr',
+            'period': period,
+            'current_value': round(value, 4),
+            'current_price': round(current_price, 2),
+            'atr_percent': round(atr_pct, 2),
+            'interpretation': f'ATR of {round(value, 4)} ({round(atr_pct, 2)}% of price) indicates {"high" if atr_pct > 3 else "normal"} volatility'
+        }
+
+else:
+    result = {'error': f'Unknown indicator: {indicator}'}
+
+result['connector'] = '$CONNECTOR'
+result['trading_pair'] = '$TRADING_PAIR'
+result['interval'] = '$INTERVAL'
+result['candles_used'] = len(closes)
+
+print(json.dumps(result, indent=2))
+PYTHON_SCRIPT
+}
+
+# Run calculation
+calculate_with_python