@hummingbot/skills 1.0.0

package/skills/hummingbot-api-setup/scripts/check_prerequisites.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Check prerequisites for Hummingbot deployment
+# Returns JSON with status of each requirement
+
+set -e
+
+check_docker() {
+    if command -v docker &> /dev/null && docker info &> /dev/null; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+check_docker_compose() {
+    if command -v docker &> /dev/null && docker compose version &> /dev/null; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+check_git() {
+    if command -v git &> /dev/null; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+check_port() {
+    local port=$1
+    if ! lsof -i :$port &> /dev/null; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+check_disk_space() {
+    # Check for at least 5GB free space
+    local free_space=$(df -BG . | awk 'NR==2 {print $4}' | sed 's/G//')
+    if [ "$free_space" -ge 5 ]; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+# Run checks
+DOCKER_OK=$(check_docker)
+COMPOSE_OK=$(check_docker_compose)
+GIT_OK=$(check_git)
+PORT_8000_OK=$(check_port 8000)
+PORT_15672_OK=$(check_port 15672)
+PORT_5432_OK=$(check_port 5432)
+DISK_OK=$(check_disk_space)
+
+# Determine overall status
+if [ "$DOCKER_OK" = "true" ] && [ "$COMPOSE_OK" = "true" ] && [ "$GIT_OK" = "true" ] && \
+   [ "$PORT_8000_OK" = "true" ] && [ "$PORT_15672_OK" = "true" ] && [ "$PORT_5432_OK" = "true" ] && \
+   [ "$DISK_OK" = "true" ]; then
+    READY="true"
+else
+    READY="false"
+fi
+
+# Output JSON
+cat << EOF
+{
+    "ready": $READY,
+    "checks": {
+        "docker": $DOCKER_OK,
+        "docker_compose": $COMPOSE_OK,
+        "git": $GIT_OK,
+        "port_8000_available": $PORT_8000_OK,
+        "port_15672_available": $PORT_15672_OK,
+        "port_5432_available": $PORT_5432_OK,
+        "disk_space_5gb": $DISK_OK
+    },
+    "messages": [
+        $([ "$DOCKER_OK" = "false" ] && echo '"Docker is not installed or not running",' || echo '')
+        $([ "$COMPOSE_OK" = "false" ] && echo '"Docker Compose is not available",' || echo '')
+        $([ "$GIT_OK" = "false" ] && echo '"Git is not installed",' || echo '')
+        $([ "$PORT_8000_OK" = "false" ] && echo '"Port 8000 is already in use",' || echo '')
+        $([ "$PORT_15672_OK" = "false" ] && echo '"Port 15672 is already in use",' || echo '')
+        $([ "$PORT_5432_OK" = "false" ] && echo '"Port 5432 is already in use",' || echo '')
+        $([ "$DISK_OK" = "false" ] && echo '"Less than 5GB disk space available",' || echo '')
+        $([ "$READY" = "true" ] && echo '"All prerequisites met, ready to deploy"' || echo '"Some prerequisites not met"')
+    ]
+}
+EOF

package/skills/hummingbot-api-setup/scripts/deploy_full_stack.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# Deploy the complete Hummingbot stack
+# Usage: ./deploy_full_stack.sh [--with-gateway] [--api-user USERNAME] [--api-pass PASSWORD]
+
+set -e
+
+# Default values
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+WITH_GATEWAY=false
+REPO_DIR="${HUMMINGBOT_API_DIR:-$HOME/hummingbot-api}"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --with-gateway)
+            WITH_GATEWAY=true
+            shift
+            ;;
+        --api-user)
+            API_USER="$2"
+            shift 2
+            ;;
+        --api-pass)
+            API_PASS="$2"
+            shift 2
+            ;;
+        --repo-dir)
+            REPO_DIR="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+echo "=== Hummingbot Full Stack Deployment ==="
+
+# Step 1: Check prerequisites
+echo ""
+echo "Step 1: Checking prerequisites..."
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PREREQ_RESULT=$("$SCRIPT_DIR/check_prerequisites.sh")
+READY=$(echo "$PREREQ_RESULT" | grep -o '"ready": [^,]*' | cut -d' ' -f2)
+
+if [ "$READY" != "true" ]; then
+    echo "Prerequisites not met:"
+    echo "$PREREQ_RESULT"
+    exit 1
+fi
+echo "All prerequisites met."
+
+# Step 2: Clone or update repository
+echo ""
+echo "Step 2: Setting up repository..."
+if [ -d "$REPO_DIR" ]; then
+    echo "Repository exists at $REPO_DIR, pulling latest..."
+    cd "$REPO_DIR"
+    git pull origin main || echo "Warning: Could not pull latest changes"
+else
+    echo "Cloning hummingbot-api repository..."
+    git clone https://github.com/hummingbot/hummingbot-api.git "$REPO_DIR"
+    cd "$REPO_DIR"
+fi
+
+# Step 3: Configure environment
+echo ""
+echo "Step 3: Configuring environment..."
+if [ -f .env.example ] && [ ! -f .env ]; then
+    cp .env.example .env
+fi
+
+# Update credentials in .env if it exists
+if [ -f .env ]; then
+    # Use sed to update or add credentials
+    if grep -q "^API_USERNAME=" .env; then
+        sed -i.bak "s/^API_USERNAME=.*/API_USERNAME=$API_USER/" .env
+    else
+        echo "API_USERNAME=$API_USER" >> .env
+    fi
+
+    if grep -q "^API_PASSWORD=" .env; then
+        sed -i.bak "s/^API_PASSWORD=.*/API_PASSWORD=$API_PASS/" .env
+    else
+        echo "API_PASSWORD=$API_PASS" >> .env
+    fi
+    rm -f .env.bak
+fi
+
+# Step 4: Pull Docker images
+echo ""
+echo "Step 4: Pulling Docker images..."
+docker compose pull
+
+# Step 5: Start services
+echo ""
+echo "Step 5: Starting services..."
+if [ "$WITH_GATEWAY" = true ]; then
+    docker compose --profile gateway up -d
+else
+    docker compose up -d
+fi
+
+# Step 6: Wait for services to be healthy
+echo ""
+echo "Step 6: Waiting for services to be healthy..."
+MAX_RETRIES=30
+RETRY_COUNT=0
+
+while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
+    if curl -s -u "$API_USER:$API_PASS" http://localhost:8000/health > /dev/null 2>&1; then
+        echo "API server is healthy!"
+        break
+    fi
+    echo "Waiting for API server... (attempt $((RETRY_COUNT + 1))/$MAX_RETRIES)"
+    sleep 2
+    RETRY_COUNT=$((RETRY_COUNT + 1))
+done
+
+if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
+    echo "Warning: API server health check timed out"
+fi
+
+# Step 7: Output status
+echo ""
+echo "=== Deployment Complete ==="
+echo ""
+
+# Get container status
+CONTAINERS=$(docker compose ps --format json 2>/dev/null || docker compose ps)
+
+cat << EOF
+{
+    "status": "deployed",
+    "api_url": "http://localhost:8000",
+    "api_docs": "http://localhost:8000/docs",
+    "credentials": {
+        "username": "$API_USER",
+        "password": "$API_PASS"
+    },
+    "gateway_enabled": $WITH_GATEWAY,
+    "repo_dir": "$REPO_DIR",
+    "next_steps": [
+        "Add exchange API keys using the keys skill",
+        "Create a controller configuration",
+        "Deploy your first trading bot"
+    ]
+}
+EOF

package/skills/hummingbot-api-setup/scripts/health_check.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# Health check for all Hummingbot services
+# Usage: ./health_check.sh [--api-url URL] [--api-user USERNAME] [--api-pass PASSWORD]
+
+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
+
+check_api_health() {
+    local response
+    local http_code
+
+    response=$(curl -s -w "\n%{http_code}" -u "$API_USER:$API_PASS" "$API_URL/health" 2>/dev/null)
+    http_code=$(echo "$response" | tail -n1)
+
+    if [ "$http_code" = "200" ]; then
+        echo "healthy"
+    else
+        echo "unhealthy"
+    fi
+}
+
+check_docker_container() {
+    local container_name=$1
+    local status
+
+    status=$(docker inspect --format='{{.State.Health.Status}}' "$container_name" 2>/dev/null || echo "not_found")
+
+    if [ "$status" = "healthy" ]; then
+        echo "healthy"
+    elif [ "$status" = "not_found" ]; then
+        # Check if container exists but doesn't have health check
+        if docker ps --format '{{.Names}}' | grep -q "^${container_name}$"; then
+            echo "running"
+        else
+            echo "not_running"
+        fi
+    else
+        echo "$status"
+    fi
+}
+
+# Check services
+API_STATUS=$(check_api_health)
+POSTGRES_STATUS=$(check_docker_container "hummingbot-postgres")
+EMQX_STATUS=$(check_docker_container "hummingbot-emqx")
+GATEWAY_STATUS=$(check_docker_container "hummingbot-gateway")
+
+# Determine overall health
+if [ "$API_STATUS" = "healthy" ]; then
+    OVERALL="healthy"
+elif [ "$API_STATUS" = "unhealthy" ] && [ "$POSTGRES_STATUS" != "not_running" ]; then
+    OVERALL="degraded"
+else
+    OVERALL="unhealthy"
+fi
+
+# Output JSON
+cat << EOF
+{
+    "overall": "$OVERALL",
+    "services": {
+        "api_server": {
+            "status": "$API_STATUS",
+            "url": "$API_URL"
+        },
+        "postgresql": {
+            "status": "$POSTGRES_STATUS"
+        },
+        "emqx": {
+            "status": "$EMQX_STATUS"
+        },
+        "gateway": {
+            "status": "$GATEWAY_STATUS"
+        }
+    },
+    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF

package/skills/hummingbot-api-setup/scripts/step1_detect_system.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Step 1: Detect operating system and architecture
+# Returns JSON with system information
+
+set -e
+
+# Detect OS
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+
+# Detect architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64|amd64) ARCH="amd64" ;;
+    aarch64|arm64) ARCH="arm64" ;;
+    armv7*|armv8*) ARCH="arm" ;;
+    armv*) ARCH="arm" ;;
+    *) ARCH="unknown" ;;
+esac
+
+# Check disk space (need 2GB minimum)
+REQUIRED_MB=2048
+if [[ "$OS" == "linux" ]] || [[ "$OS" == "darwin" ]]; then
+    AVAILABLE_MB=$(df -m . 2>/dev/null | tail -1 | awk '{print $4}')
+else
+    AVAILABLE_MB=0
+fi
+
+if [[ -n "$AVAILABLE_MB" ]] && [[ $AVAILABLE_MB -ge $REQUIRED_MB ]]; then
+    DISK_OK="true"
+else
+    DISK_OK="false"
+fi
+
+# Check if running in container
+if [ -f /.dockerenv ] || grep -q docker /proc/1/cgroup 2>/dev/null; then
+    IN_CONTAINER="true"
+else
+    IN_CONTAINER="false"
+fi
+
+# Determine if supported
+if [[ "$OS" == "linux" ]] || [[ "$OS" == "darwin" ]]; then
+    SUPPORTED="true"
+else
+    SUPPORTED="false"
+fi
+
+# Detect package manager (Linux only)
+PKG_MANAGER="none"
+if [[ "$OS" == "linux" ]]; then
+    if command -v apt-get &> /dev/null; then
+        PKG_MANAGER="apt-get"
+    elif command -v yum &> /dev/null; then
+        PKG_MANAGER="yum"
+    elif command -v dnf &> /dev/null; then
+        PKG_MANAGER="dnf"
+    elif command -v apk &> /dev/null; then
+        PKG_MANAGER="apk"
+    elif command -v pacman &> /dev/null; then
+        PKG_MANAGER="pacman"
+    fi
+elif [[ "$OS" == "darwin" ]]; then
+    if command -v brew &> /dev/null; then
+        PKG_MANAGER="homebrew"
+    fi
+fi
+
+cat << EOF
+{
+    "os": "$OS",
+    "arch": "$ARCH",
+    "supported": $SUPPORTED,
+    "disk_space_mb": ${AVAILABLE_MB:-0},
+    "disk_space_ok": $DISK_OK,
+    "required_disk_mb": $REQUIRED_MB,
+    "in_container": $IN_CONTAINER,
+    "package_manager": "$PKG_MANAGER",
+    "messages": [
+        "Operating System: $OS",
+        "Architecture: $ARCH",
+        "Disk Space: ${AVAILABLE_MB:-unknown}MB available (${REQUIRED_MB}MB required)",
+        $([ "$DISK_OK" = "false" ] && echo "\"WARNING: Insufficient disk space\"," || echo "")
+        $([ "$SUPPORTED" = "false" ] && echo "\"WARNING: Unsupported operating system\"," || echo "")
+        $([ "$IN_CONTAINER" = "true" ] && echo "\"NOTE: Running inside a container\"," || echo "")
+        "Package Manager: $PKG_MANAGER"
+    ]
+}
+EOF

package/skills/hummingbot-api-setup/scripts/step2_check_dependencies.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# Step 2: Check for required dependencies
+# Returns JSON with dependency status
+
+set -e
+
+check_command() {
+    if command -v "$1" &> /dev/null; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+# Check each dependency
+GIT_OK=$(check_command git)
+CURL_OK=$(check_command curl)
+DOCKER_OK=$(check_command docker)
+MAKE_OK=$(check_command make)
+
+# Check docker-compose (either plugin or standalone)
+if docker compose version &> /dev/null 2>&1; then
+    DOCKER_COMPOSE_OK="true"
+    DOCKER_COMPOSE_TYPE="plugin"
+elif command -v docker-compose &> /dev/null; then
+    DOCKER_COMPOSE_OK="true"
+    DOCKER_COMPOSE_TYPE="standalone"
+else
+    DOCKER_COMPOSE_OK="false"
+    DOCKER_COMPOSE_TYPE="none"
+fi
+
+# Build missing list
+MISSING=()
+[ "$GIT_OK" = "false" ] && MISSING+=("git")
+[ "$CURL_OK" = "false" ] && MISSING+=("curl")
+[ "$DOCKER_OK" = "false" ] && MISSING+=("docker")
+[ "$DOCKER_COMPOSE_OK" = "false" ] && MISSING+=("docker-compose")
+[ "$MAKE_OK" = "false" ] && MISSING+=("make")
+
+# Determine overall status
+if [ ${#MISSING[@]} -eq 0 ]; then
+    ALL_OK="true"
+else
+    ALL_OK="false"
+fi
+
+# Convert missing array to JSON
+MISSING_JSON=$(printf '%s\n' "${MISSING[@]}" | jq -R . | jq -s .)
+
+cat << EOF
+{
+    "all_dependencies_met": $ALL_OK,
+    "dependencies": {
+        "git": {
+            "installed": $GIT_OK,
+            "purpose": "Clone repositories"
+        },
+        "curl": {
+            "installed": $CURL_OK,
+            "purpose": "Download files and make API calls"
+        },
+        "docker": {
+            "installed": $DOCKER_OK,
+            "purpose": "Run containerized services"
+        },
+        "docker_compose": {
+            "installed": $DOCKER_COMPOSE_OK,
+            "type": "$DOCKER_COMPOSE_TYPE",
+            "purpose": "Orchestrate multi-container deployments"
+        },
+        "make": {
+            "installed": $MAKE_OK,
+            "purpose": "Run build and setup commands"
+        }
+    },
+    "missing": $MISSING_JSON,
+    "missing_count": ${#MISSING[@]},
+    "next_step": $([ "$ALL_OK" = "true" ] && echo '"All dependencies installed. Proceed to step 4 (check Docker status)."' || echo '"Install missing dependencies using step3_install_dependency.sh"')
+}
+EOF

package/skills/keys-manager/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: keys-manager
+description: Manage exchange API keys and credentials for Hummingbot trading. Use this skill when the user wants to add, remove, or list API credentials for exchanges like Binance, Coinbase, Kraken, etc.
+license: Apache-2.0
+---
+
+# Hummingbot Keys Skill
+
+This skill manages exchange API keys and credentials for Hummingbot. It uses **progressive disclosure** to guide users through the setup process step by step.
+
+## Prerequisites
+
+- Hummingbot API server must be running (use the setup skill first)
+- API server credentials (default: admin/admin)
+
+## Quick Start: Setup Connector (Progressive Disclosure)
+
+The `setup_connector.sh` script uses a 4-step progressive flow:
+
+### Step 1: List Available Exchanges
+
+```bash
+./scripts/setup_connector.sh
+```
+
+Shows all available connectors and current account status.
+
+### Step 2: Show Required Credentials
+
+```bash
+./scripts/setup_connector.sh --connector binance
+```
+
+Shows what credential fields are required for that exchange.
+
+### Step 3: Select Account
+
+```bash
+./scripts/setup_connector.sh --connector binance \
+    --credentials '{"binance_api_key":"YOUR_KEY","binance_api_secret":"YOUR_SECRET"}'
+```
+
+Shows available accounts and prompts you to select one.
+
+### Step 4: Connect
+
+```bash
+./scripts/setup_connector.sh --connector binance \
+    --credentials '{"binance_api_key":"YOUR_KEY","binance_api_secret":"YOUR_SECRET"}' \
+    --account master_account
+```
+
+Completes the connection. Use `--force` to override existing credentials.
+
+## Other Scripts
+
+### List All Connectors
+
+```bash
+./scripts/list_connectors.sh
+```
+
+### Get Connector Requirements
+
+```bash
+./scripts/get_connector_config.sh --connector binance
+```
+
+### Add Credentials Directly
+
+```bash
+./scripts/add_credentials.sh \
+    --connector binance \
+    --account master_account \
+    --credentials '{"binance_api_key": "KEY", "binance_api_secret": "SECRET"}'
+```
+
+### Remove Credentials
+
+```bash
+./scripts/remove_credentials.sh \
+    --connector binance \
+    --account master_account
+```
+
+### List Account Credentials
+
+```bash
+./scripts/list_account_credentials.sh --account master_account
+```
+
+## Supported Exchanges
+
+### Centralized Exchanges (CEX)
+
+| Exchange | Connector Name | Required Fields |
+|----------|----------------|-----------------|
+| Binance | `binance` | api_key, api_secret |
+| Binance Perpetual | `binance_perpetual` | api_key, api_secret |
+| Coinbase | `coinbase_advanced_trade` | api_key, api_secret |
+| Kraken | `kraken` | api_key, api_secret |
+| KuCoin | `kucoin` | api_key, api_secret, passphrase |
+| Gate.io | `gate_io` | api_key, api_secret |
+| OKX | `okx` | api_key, api_secret, passphrase |
+| Bybit | `bybit` | api_key, api_secret |
+| Hyperliquid | `hyperliquid_perpetual` | address, secret_key |
+
+## Security Notes
+
+- **Never log credentials** - credentials should only be passed to scripts, never echoed
+- **Credentials are encrypted** - Hummingbot encrypts all stored credentials
+- **API key permissions** - recommend users create keys with minimal required permissions
+
+## API Endpoints Used
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/connectors/` | GET | List available connectors |
+| `/connectors/{name}/config-map` | GET | Get required credential fields |
+| `/accounts/` | GET | List accounts |
+| `/accounts/{name}/credentials` | GET | List account credentials |
+| `/accounts/{name}/credentials` | POST | Add credentials |
+| `/accounts/{name}/credentials/{connector}` | DELETE | Remove credentials |
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Invalid credentials" | Wrong API key/secret | Verify credentials are correct |
+| "Connector not found" | Typo in connector name | Use Step 1 to see valid names |
+| "Account not found" | Account doesn't exist | Use default "master_account" |
+| "Credentials already exist" | Connector already configured | Use --force to override |