@hummingbot/skills 1.0.0

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

@@ -0,0 +1,158 @@
+#!/bin/bash
+# Fetch candlestick (OHLCV) data for a trading pair
+# Usage: ./get_candles.sh --connector CONNECTOR --pair TRADING_PAIR [--interval INTERVAL] [--days DAYS]
+
+set -e
+
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+CONNECTOR=""
+TRADING_PAIR=""
+INTERVAL="1h"
+DAYS=30
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --connector)
+            CONNECTOR="$2"
+            shift 2
+            ;;
+        --pair)
+            TRADING_PAIR="$2"
+            shift 2
+            ;;
+        --interval)
+            INTERVAL="$2"
+            shift 2
+            ;;
+        --days)
+            DAYS="$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
+
+# Validate interval
+case "$INTERVAL" in
+    1m|5m|15m|30m|1h|4h|1d|1w)
+        ;;
+    *)
+        echo '{"error": "Invalid interval. Use 1m, 5m, 15m, 30m, 1h, 4h, 1d, or 1w"}'
+        exit 1
+        ;;
+esac
+
+# Calculate max_records based on interval
+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
+        ;;
+    *w)
+        MAX_RECORDS=$((DAYS / 7))
+        ;;
+esac
+
+# Calculate timestamps for historical fetch
+END_TIME=$(date +%s)
+START_TIME=$((END_TIME - DAYS * 24 * 3600))
+
+# Step 1: 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 "[]")
+
+# Step 2: 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 "[]")
+
+# Step 3: Merge and deduplicate by timestamp (real-time overrides historical)
+CANDLES=$(echo "$HISTORICAL $REALTIME" | jq -s '.[0] + .[1] | group_by(.timestamp) | map(.[0]) | sort_by(.timestamp)')
+
+# Check for error
+if echo "$CANDLES" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to fetch candles\", \"detail\": $CANDLES}"
+    exit 1
+fi
+
+# Get candle count
+TOTAL=$(echo "$CANDLES" | jq 'length')
+
+# Get latest candle stats
+if [ "$TOTAL" -gt 0 ]; then
+    LATEST=$(echo "$CANDLES" | jq '.[-1]')
+    FIRST=$(echo "$CANDLES" | jq '.[0]')
+    LATEST_CLOSE=$(echo "$LATEST" | jq '.close')
+    FIRST_CLOSE=$(echo "$FIRST" | jq '.close')
+
+    # Calculate price change
+    CHANGE=$(echo "scale=4; ($LATEST_CLOSE - $FIRST_CLOSE) / $FIRST_CLOSE * 100" | bc 2>/dev/null || echo "0")
+
+    # Get high/low for period
+    HIGH=$(echo "$CANDLES" | jq '[.[].high] | max')
+    LOW=$(echo "$CANDLES" | jq '[.[].low] | min')
+    TOTAL_VOLUME=$(echo "$CANDLES" | jq '[.[].volume] | add')
+else
+    LATEST="null"
+    CHANGE="0"
+    HIGH="0"
+    LOW="0"
+    TOTAL_VOLUME="0"
+fi
+
+cat << EOF
+{
+    "connector": "$CONNECTOR",
+    "trading_pair": "$TRADING_PAIR",
+    "interval": "$INTERVAL",
+    "days": $DAYS,
+    "total_candles": $TOTAL,
+    "summary": {
+        "latest_close": $LATEST_CLOSE,
+        "period_high": $HIGH,
+        "period_low": $LOW,
+        "price_change_pct": $CHANGE,
+        "total_volume": $TOTAL_VOLUME
+    },
+    "latest_candle": $LATEST,
+    "candles": $CANDLES
+}
+EOF

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

@@ -0,0 +1,112 @@
+#!/bin/bash
+# Get funding rate for perpetual trading pairs
+# Usage: ./get_funding_rate.sh --connector CONNECTOR_PERPETUAL --pair TRADING_PAIR
+
+set -e
+
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+CONNECTOR=""
+TRADING_PAIR=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --connector)
+            CONNECTOR="$2"
+            shift 2
+            ;;
+        --pair)
+            TRADING_PAIR="$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 (must be perpetual)"}'
+    exit 1
+fi
+
+if [ -z "$TRADING_PAIR" ]; then
+    echo '{"error": "trading pair is required. Use --pair TRADING_PAIR"}'
+    exit 1
+fi
+
+# Check if connector is perpetual
+if [[ "$CONNECTOR" != *"perpetual"* ]]; then
+    echo "{\"error\": \"Connector '$CONNECTOR' is not a perpetual connector. Funding rates are only available for perpetual connectors (e.g., binance_perpetual)\"}"
+    exit 1
+fi
+
+# Fetch funding rate (POST request with JSON body)
+FUNDING=$(curl -s -u "$API_USER:$API_PASS" \
+    -X POST "$API_URL/market-data/funding-info" \
+    -H "Content-Type: application/json" \
+    -d "{\"connector_name\": \"$CONNECTOR\", \"trading_pair\": \"$TRADING_PAIR\"}")
+
+# Check for error
+if echo "$FUNDING" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to fetch funding rate\", \"detail\": $FUNDING}"
+    exit 1
+fi
+
+# Extract and format data
+FUNDING_RATE=$(echo "$FUNDING" | jq '.funding_rate // 0')
+MARK_PRICE=$(echo "$FUNDING" | jq '.mark_price // 0')
+INDEX_PRICE=$(echo "$FUNDING" | jq '.index_price // 0')
+NEXT_FUNDING_TIME=$(echo "$FUNDING" | jq '.next_funding_time // 0')
+
+# Calculate funding rate percentage
+FUNDING_PCT=$(echo "scale=6; $FUNDING_RATE * 100" | bc 2>/dev/null || echo "0")
+
+# Calculate annualized rate (3 funding periods per day * 365)
+ANNUAL_PCT=$(echo "scale=2; $FUNDING_PCT * 3 * 365" | bc 2>/dev/null || echo "0")
+
+# Format next funding time
+if [ "$NEXT_FUNDING_TIME" != "0" ] && [ "$NEXT_FUNDING_TIME" != "null" ]; then
+    NEXT_TIME_STR=$(date -d "@$NEXT_FUNDING_TIME" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || date -r "$NEXT_FUNDING_TIME" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "N/A")
+else
+    NEXT_TIME_STR="N/A"
+fi
+
+# Determine sentiment
+if (( $(echo "$FUNDING_RATE > 0.0001" | bc -l 2>/dev/null || echo 0) )); then
+    SENTIMENT="bullish (longs pay shorts)"
+elif (( $(echo "$FUNDING_RATE < -0.0001" | bc -l 2>/dev/null || echo 0) )); then
+    SENTIMENT="bearish (shorts pay longs)"
+else
+    SENTIMENT="neutral"
+fi
+
+cat << EOF
+{
+    "connector": "$CONNECTOR",
+    "trading_pair": "$TRADING_PAIR",
+    "funding_rate": $FUNDING_RATE,
+    "funding_rate_pct": $FUNDING_PCT,
+    "annualized_rate_pct": $ANNUAL_PCT,
+    "mark_price": $MARK_PRICE,
+    "index_price": $INDEX_PRICE,
+    "next_funding_time": "$NEXT_TIME_STR",
+    "sentiment": "$SENTIMENT",
+    "interpretation": "Current funding rate of ${FUNDING_PCT}% means ${SENTIMENT}"
+}
+EOF

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

@@ -0,0 +1,86 @@
+#!/bin/bash
+# Get current prices for trading pairs
+# Usage: ./get_price.sh --connector CONNECTOR --pairs "PAIR1,PAIR2"
+
+set -e
+
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+CONNECTOR=""
+PAIRS=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --connector)
+            CONNECTOR="$2"
+            shift 2
+            ;;
+        --pairs)
+            PAIRS="$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 "$PAIRS" ]; then
+    echo '{"error": "trading pairs are required. Use --pairs \"PAIR1,PAIR2\""}'
+    exit 1
+fi
+
+# Convert pairs to JSON array format
+PAIRS_JSON=$(echo "$PAIRS" | tr ',' '\n' | jq -R . | jq -s .)
+
+# Fetch prices (POST request with JSON body)
+RESPONSE=$(curl -s -u "$API_USER:$API_PASS" \
+    -X POST "$API_URL/market-data/prices" \
+    -H "Content-Type: application/json" \
+    -d "{\"connector_name\": \"$CONNECTOR\", \"trading_pairs\": $PAIRS_JSON}")
+
+# Check for error
+if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to fetch prices\", \"detail\": $RESPONSE}"
+    exit 1
+fi
+
+# Extract prices and timestamp from response
+PRICES=$(echo "$RESPONSE" | jq '.prices')
+TIMESTAMP=$(echo "$RESPONSE" | jq -r '.timestamp // 0')
+
+# Format timestamp
+if [ "$TIMESTAMP" != "0" ] && [ "$TIMESTAMP" != "null" ]; then
+    TIME_STR=$(date -d "@${TIMESTAMP%.*}" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || date -r "${TIMESTAMP%.*}" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "N/A")
+else
+    TIME_STR="N/A"
+fi
+
+cat << EOF
+{
+    "connector": "$CONNECTOR",
+    "prices": $PRICES,
+    "timestamp": "$TIME_STR",
+    "pairs_requested": $(echo "$PAIRS" | tr ',' '\n' | jq -R . | jq -s .)
+}
+EOF

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

@@ -0,0 +1,47 @@
+#!/bin/bash
+# List connectors that support candle data
+# Usage: ./list_candle_connectors.sh
+
+set -e
+
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --api-url)
+            API_URL="$2"
+            shift 2
+            ;;
+        --api-user)
+            API_USER="$2"
+            shift 2
+            ;;
+        --api-pass)
+            API_PASS="$2"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Get list of connectors that support candles
+CONNECTORS=$(curl -s -u "$API_USER:$API_PASS" "$API_URL/market-data/available-candle-connectors")
+
+# Check for error
+if echo "$CONNECTORS" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to get candle connectors\", \"detail\": $CONNECTORS}"
+    exit 1
+fi
+
+cat << EOF
+{
+    "connectors": $CONNECTORS,
+    "total": $(echo "$CONNECTORS" | jq 'length'),
+    "supported_intervals": ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]
+}
+EOF

package/skills/executor-creator/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: executor-creator
+description: Create and manage Hummingbot trading executors (position, grid, DCA, TWAP) directly via API. Use this skill when the user wants to create trading positions, set up grid trading, dollar-cost averaging, or any automated trading execution.
+license: Apache-2.0
+---
+
+# Hummingbot Executors Skill
+
+This skill manages **executors** - lightweight trading components that run directly via the Hummingbot API. Executors are the recommended starting point for new users.
+
+## Quick Start: Setup Executor (Progressive Disclosure)
+
+The `setup_executor.sh` script guides you through creating executors step by step:
+
+### Step 1: List Available Executor Types
+
+```bash
+./scripts/setup_executor.sh
+```
+
+Shows all executor types with descriptions and current summary.
+
+### Step 2: Get Config Schema
+
+```bash
+./scripts/setup_executor.sh --type position_executor
+```
+
+Shows required fields and example configuration.
+
+### Step 3: Create Executor
+
+```bash
+./scripts/setup_executor.sh --type position_executor --config '{
+    "connector_name": "hyperliquid_perpetual",
+    "trading_pair": "BTC-USD",
+    "side": "BUY",
+    "amount": "0.001",
+    "triple_barrier_config": {
+        "stop_loss": "0.02",
+        "take_profit": "0.04",
+        "time_limit": 3600
+    }
+}'
+```
+
+## Executor Types
+
+### 1. Position Executor (Recommended Start)
+
+Single position with triple barrier risk management:
+- **Stop Loss**: Exit if price moves against you
+- **Take Profit**: Exit when target reached
+- **Time Limit**: Exit after duration expires
+
+```bash
+./scripts/setup_executor.sh --type position_executor --config '{
+    "connector_name": "hyperliquid_perpetual",
+    "trading_pair": "BTC-USD",
+    "side": "BUY",
+    "amount": "0.001",
+    "triple_barrier_config": {
+        "stop_loss": "0.02",
+        "take_profit": "0.04",
+        "time_limit": 3600
+    }
+}'
+```
+
+### 2. Grid Executor
+
+Automated grid trading with multiple buy/sell levels:
+
+```bash
+./scripts/setup_executor.sh --type grid_executor --config '{
+    "connector_name": "hyperliquid_perpetual",
+    "trading_pair": "BTC-USD",
+    "start_price": "80000",
+    "end_price": "90000",
+    "total_amount_quote": "1000",
+    "total_levels": 10,
+    "side": "BUY"
+}'
+```
+
+### 3. DCA Executor
+
+Dollar-cost averaging with multiple entry points:
+
+```bash
+./scripts/setup_executor.sh --type dca_executor --config '{
+    "connector_name": "hyperliquid_perpetual",
+    "trading_pair": "BTC-USD",
+    "side": "BUY",
+    "total_amount_quote": "1000",
+    "n_levels": 5,
+    "time_limit": 86400
+}'
+```
+
+### 4. TWAP Executor
+
+Time-weighted average price for large orders with minimal market impact.
+
+### 5. Arbitrage Executor
+
+Cross-exchange price arbitrage.
+
+### 6. XEMM Executor
+
+Cross-exchange market making.
+
+### 7. Order Executor
+
+Simple order execution with retry logic.
+
+## Management Scripts
+
+### List Active Executors
+
+```bash
+./scripts/list_executors.sh [--status RUNNING] [--connector hyperliquid_perpetual]
+```
+
+### Get Executor Details
+
+```bash
+./scripts/get_executor.sh --id <executor_id>
+```
+
+### Stop Executor
+
+```bash
+# Stop and close positions
+./scripts/stop_executor.sh --id <executor_id>
+
+# Stop but keep position open
+./scripts/stop_executor.sh --id <executor_id> --keep-position
+```
+
+### Get Summary Stats
+
+```bash
+./scripts/get_executors_summary.sh
+```
+
+### Manage Held Positions
+
+```bash
+# List all positions from stopped executors
+./scripts/get_positions.sh
+
+# Get specific position
+./scripts/get_position.sh --connector hyperliquid_perpetual --pair BTC-USD
+
+# Clear position (after manual close)
+./scripts/clear_position.sh --connector hyperliquid_perpetual --pair BTC-USD
+```
+
+## Position Executor Configuration
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connector_name` | string | Yes | Exchange connector |
+| `trading_pair` | string | Yes | Trading pair |
+| `side` | enum | Yes | BUY or SELL |
+| `amount` | Decimal | Yes | Position size |
+| `entry_price` | Decimal | No | Limit price (market if omitted) |
+| `triple_barrier_config.stop_loss` | Decimal | No | Stop loss (e.g., 0.02 = 2%) |
+| `triple_barrier_config.take_profit` | Decimal | No | Take profit percentage |
+| `triple_barrier_config.time_limit` | int | No | Max duration in seconds |
+| `leverage` | int | No | Leverage (default: 1) |
+
+### Triple Barrier Explained
+
+```
+                    Take Profit (exit with gain)
+                    ────────────────────────
+                         ↑
+         Price moves up  │
+                         │
+Entry ──────────────────●──────────────────── Time Limit (exit)
+                         │
+         Price moves down│
+                         ↓
+                    ────────────────────────
+                    Stop Loss (exit with loss)
+```
+
+The position exits when ANY barrier is hit first.
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/executors/types/available` | GET | List executor types |
+| `/executors/types/{type}/config` | GET | Get config schema |
+| `/executors` | POST | Create executor |
+| `/executors/search` | POST | List/filter executors |
+| `/executors/summary` | GET | Get summary stats |
+| `/executors/{id}` | GET | Get executor details |
+| `/executors/{id}/stop` | POST | Stop executor |
+| `/executors/positions/summary` | GET | Get held positions |
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Unknown executor type" | Invalid type | Use Step 1 to see valid types |
+| "Insufficient balance" | Not enough funds | Reduce amount or add funds |
+| "Invalid trading pair" | Pair not on exchange | Check exchange for valid pairs |
+| "Connector not configured" | Missing API keys | Use keys skill to add credentials |

package/skills/executor-creator/scripts/clear_position.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Clear a held position (use after manually closing on exchange)
+# Usage: ./clear_position.sh --connector CONNECTOR --pair PAIR
+
+set -e
+
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+CONNECTOR=""
+PAIR=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --connector) CONNECTOR="$2"; shift 2 ;;
+        --pair) PAIR="$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
+
+if [ -z "$CONNECTOR" ]; then
+    echo '{"error": "connector is required. Use --connector CONNECTOR"}'
+    exit 1
+fi
+
+if [ -z "$PAIR" ]; then
+    echo '{"error": "trading pair is required. Use --pair PAIR"}'
+    exit 1
+fi
+
+# Clear position
+RESPONSE=$(curl -s -X DELETE \
+    -u "$API_USER:$API_PASS" \
+    "$API_URL/executors/positions/$CONNECTOR/$PAIR")
+
+# Check for error
+if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to clear position for $CONNECTOR/$PAIR\", \"detail\": $RESPONSE}"
+    exit 1
+fi
+
+cat << EOF
+{
+    "status": "success",
+    "action": "position_cleared",
+    "connector": "$CONNECTOR",
+    "trading_pair": "$PAIR",
+    "response": $RESPONSE
+}
+EOF