@hummingbot/skills 1.0.0 → 1.0.5

package/skills/portfolio/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: portfolio
+description: View portfolio balances, positions, and history across all connected exchanges. Use this skill when the user wants to check their balance, see positions, view portfolio distribution, or track portfolio history.
+license: Apache-2.0
+creator-github-handle: fengtality
+---
+
+# portfolio
+
+This skill provides portfolio visibility across all connected exchanges and accounts.
+
+## Prerequisites
+
+- Hummingbot API server must be running
+- Exchange credentials configured via keys-manager skill
+
+## Quick Start
+
+### Get Current Portfolio State
+
+```bash
+./scripts/get_state.sh
+```
+
+Filter by specific connectors:
+```bash
+./scripts/get_state.sh --connector hyperliquid_perpetual
+```
+
+Force refresh balances from exchange:
+```bash
+./scripts/get_state.sh --refresh
+```
+
+### Get Portfolio Distribution
+
+See token allocation across accounts:
+```bash
+./scripts/get_distribution.sh
+```
+
+### Get Portfolio History
+
+View historical portfolio values:
+```bash
+./scripts/get_history.sh --days 7
+```
+
+With interval sampling:
+```bash
+./scripts/get_history.sh --days 30 --interval 1d
+```
+
+### Get Full Portfolio Overview
+
+Combined view with balances, positions, and orders:
+```bash
+./scripts/get_overview.sh
+```
+
+## Scripts
+
+### get_state.sh
+
+Fetches current portfolio state with token balances.
+
+```bash
+./scripts/get_state.sh [OPTIONS]
+
+Options:
+  --account ACCOUNT      Filter by account name (default: all)
+  --connector CONNECTOR  Filter by connector name
+  --refresh              Force refresh from exchange (slower but accurate)
+  --skip-gateway         Skip Gateway wallets (faster for CEX-only)
+```
+
+### get_distribution.sh
+
+Shows portfolio distribution by token with percentages.
+
+```bash
+./scripts/get_distribution.sh [OPTIONS]
+
+Options:
+  --account ACCOUNT      Filter by account name
+  --connector CONNECTOR  Filter by connector name
+```
+
+### get_history.sh
+
+Retrieves historical portfolio data with pagination.
+
+```bash
+./scripts/get_history.sh [OPTIONS]
+
+Options:
+  --days DAYS           Number of days of history (default: 7)
+  --interval INTERVAL   Data granularity: 5m, 15m, 30m, 1h, 4h, 12h, 1d (default: 1h)
+  --account ACCOUNT     Filter by account name
+  --connector CONNECTOR Filter by connector name
+  --limit LIMIT         Max records to return (default: 100)
+```
+
+### get_overview.sh
+
+Comprehensive portfolio view including:
+- Token balances
+- Perpetual positions
+- Active orders
+
+```bash
+./scripts/get_overview.sh [OPTIONS]
+
+Options:
+  --account ACCOUNT      Filter by account name
+  --connector CONNECTOR  Filter by connector name
+  --no-balances          Skip token balances
+  --no-positions         Skip perpetual positions
+  --no-orders            Skip active orders
+```
+
+## Output Examples
+
+### Portfolio State
+```json
+{
+  "accounts": {
+    "master_account": {
+      "hyperliquid_perpetual": {
+        "balances": {
+          "USDC": {"total": 1000.0, "available": 850.0}
+        }
+      }
+    }
+  },
+  "total_value_usd": 1000.0
+}
+```
+
+### Portfolio Distribution
+```json
+{
+  "tokens": {
+    "USDC": {
+      "total_value": 1000.0,
+      "percentage": 100.0,
+      "accounts": ["master_account"]
+    }
+  }
+}
+```
+
+### Portfolio History
+```json
+{
+  "data": [
+    {"timestamp": 1706400000, "total_value": 1000.0},
+    {"timestamp": 1706486400, "total_value": 1050.0}
+  ],
+  "interval": "1d",
+  "period": "7d"
+}
+```
+
+## API Endpoints Used
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/portfolio/state` | POST | Get current portfolio state |
+| `/portfolio/distribution` | POST | Get token distribution |
+| `/portfolio/history` | POST | Get historical data |
+| `/trading/{account}/{connector}/orders` | GET | Get active orders |
+| `/trading/{account}/{connector}/positions` | GET | Get perpetual positions |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_URL` | `http://localhost:8000` | API base URL |
+| `API_USER` | `admin` | API username |
+| `API_PASS` | `admin` | API password |

package/skills/portfolio/scripts/get_distribution.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Get portfolio distribution by token
+# Usage: ./get_distribution.sh [--account NAME] [--connector NAME]
+
+set -e
+
+# Load .env if present (check current dir, ~/.hummingbot/, ~/)
+for f in .env ~/.hummingbot/.env ~/.env; do [ -f "$f" ] && source "$f" && break; done
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+
+ACCOUNT=""
+CONNECTOR=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --account) ACCOUNT="$2"; shift 2 ;;
+        --connector) CONNECTOR="$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
+
+# Build request body
+REQUEST='{}'
+
+if [ -n "$ACCOUNT" ]; then
+    REQUEST=$(echo "$REQUEST" | jq --arg acc "$ACCOUNT" '. + {account_names: [$acc]}')
+fi
+
+if [ -n "$CONNECTOR" ]; then
+    REQUEST=$(echo "$REQUEST" | jq --arg conn "$CONNECTOR" '. + {connector_names: [$conn]}')
+fi
+
+# Fetch distribution
+RESPONSE=$(curl -s -X POST \
+    -u "$API_USER:$API_PASS" \
+    -H "Content-Type: application/json" \
+    -d "$REQUEST" \
+    "$API_URL/portfolio/distribution")
+
+# Check for error
+if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to get portfolio distribution\", \"detail\": $RESPONSE}"
+    exit 1
+fi
+
+echo "$RESPONSE" | jq '.'

package/skills/portfolio/scripts/get_history.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Get portfolio history with interval sampling
+# Usage: ./get_history.sh [--days N] [--interval 1h] [--account NAME] [--connector NAME]
+
+set -e
+
+# Load .env if present (check current dir, ~/.hummingbot/, ~/)
+for f in .env ~/.hummingbot/.env ~/.env; do [ -f "$f" ] && source "$f" && break; done
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+
+DAYS=7
+INTERVAL="1h"
+ACCOUNT=""
+CONNECTOR=""
+LIMIT=100
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --days) DAYS="$2"; shift 2 ;;
+        --interval) INTERVAL="$2"; shift 2 ;;
+        --account) ACCOUNT="$2"; shift 2 ;;
+        --connector) CONNECTOR="$2"; shift 2 ;;
+        --limit) LIMIT="$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
+
+# Calculate start_time (N days ago in seconds)
+START_TIME=$(($(date +%s) - (DAYS * 86400)))
+
+# Build request body
+REQUEST=$(jq -n \
+    --argjson start_time "$START_TIME" \
+    --arg interval "$INTERVAL" \
+    --argjson limit "$LIMIT" \
+    '{start_time: $start_time, interval: $interval, limit: $limit}')
+
+if [ -n "$ACCOUNT" ]; then
+    REQUEST=$(echo "$REQUEST" | jq --arg acc "$ACCOUNT" '. + {account_names: [$acc]}')
+fi
+
+if [ -n "$CONNECTOR" ]; then
+    REQUEST=$(echo "$REQUEST" | jq --arg conn "$CONNECTOR" '. + {connector_names: [$conn]}')
+fi
+
+# Fetch history
+RESPONSE=$(curl -s -X POST \
+    -u "$API_USER:$API_PASS" \
+    -H "Content-Type: application/json" \
+    -d "$REQUEST" \
+    "$API_URL/portfolio/history")
+
+# Check for error
+if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to get portfolio history\", \"detail\": $RESPONSE}"
+    exit 1
+fi
+
+# Add query metadata
+cat << EOF
+{
+    "query": {
+        "days": $DAYS,
+        "interval": "$INTERVAL",
+        "start_time": $START_TIME
+    },
+    "response": $RESPONSE
+}
+EOF

package/skills/portfolio/scripts/get_overview.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Get comprehensive portfolio overview with balances, positions, and orders
+# Usage: ./get_overview.sh [--account NAME] [--connector NAME] [--no-balances] [--no-positions] [--no-orders]
+
+set -e
+
+# Load .env if present (check current dir, ~/.hummingbot/, ~/)
+for f in .env ~/.hummingbot/.env ~/.env; do [ -f "$f" ] && source "$f" && break; done
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+
+ACCOUNT=""
+CONNECTOR=""
+INCLUDE_BALANCES=true
+INCLUDE_POSITIONS=true
+INCLUDE_ORDERS=true
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --account) ACCOUNT="$2"; shift 2 ;;
+        --connector) CONNECTOR="$2"; shift 2 ;;
+        --no-balances) INCLUDE_BALANCES=false; shift ;;
+        --no-positions) INCLUDE_POSITIONS=false; shift ;;
+        --no-orders) INCLUDE_ORDERS=false; shift ;;
+        --api-url) API_URL="$2"; shift 2 ;;
+        --api-user) API_USER="$2"; shift 2 ;;
+        --api-pass) API_PASS="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+# Build filter request
+FILTER_REQUEST='{}'
+if [ -n "$ACCOUNT" ]; then
+    FILTER_REQUEST=$(echo "$FILTER_REQUEST" | jq --arg acc "$ACCOUNT" '. + {account_names: [$acc]}')
+fi
+if [ -n "$CONNECTOR" ]; then
+    FILTER_REQUEST=$(echo "$FILTER_REQUEST" | jq --arg conn "$CONNECTOR" '. + {connector_names: [$conn]}')
+fi
+
+# Initialize results
+BALANCES="{}"
+POSITIONS="[]"
+ORDERS="[]"
+
+# Fetch balances
+if [ "$INCLUDE_BALANCES" = true ]; then
+    BALANCES=$(curl -s -X POST \
+        -u "$API_USER:$API_PASS" \
+        -H "Content-Type: application/json" \
+        -d "$FILTER_REQUEST" \
+        "$API_URL/portfolio/state" 2>/dev/null || echo '{}')
+fi
+
+# Fetch positions (for perpetual connectors)
+if [ "$INCLUDE_POSITIONS" = true ]; then
+    # Get positions from executors endpoint
+    POSITIONS=$(curl -s -X GET \
+        -u "$API_USER:$API_PASS" \
+        "$API_URL/executors/positions/summary" 2>/dev/null || echo '[]')
+fi
+
+# Fetch active orders
+if [ "$INCLUDE_ORDERS" = true ]; then
+    # Search for active orders
+    ORDER_REQUEST='{"status": ["OPEN", "PENDING"], "limit": 50}'
+    ORDERS=$(curl -s -X POST \
+        -u "$API_USER:$API_PASS" \
+        -H "Content-Type: application/json" \
+        -d "$ORDER_REQUEST" \
+        "$API_URL/trading/search-orders/" 2>/dev/null || echo '{"data": []}')
+    ORDERS=$(echo "$ORDERS" | jq '.data // []')
+fi
+
+# Build overview response
+cat << EOF
+{
+    "overview": {
+        "timestamp": $(date +%s),
+        "filters": {
+            "account": $([ -n "$ACCOUNT" ] && echo "\"$ACCOUNT\"" || echo "null"),
+            "connector": $([ -n "$CONNECTOR" ] && echo "\"$CONNECTOR\"" || echo "null")
+        }
+    },
+    "balances": $BALANCES,
+    "positions": $POSITIONS,
+    "active_orders": $ORDERS,
+    "summary": {
+        "has_balances": $([ "$BALANCES" != "{}" ] && echo "true" || echo "false"),
+        "position_count": $(echo "$POSITIONS" | jq 'if type == "array" then length else 0 end'),
+        "order_count": $(echo "$ORDERS" | jq 'if type == "array" then length else 0 end')
+    }
+}
+EOF

package/skills/portfolio/scripts/get_state.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Get current portfolio state with balances
+# Usage: ./get_state.sh [--account NAME] [--connector NAME] [--refresh] [--skip-gateway]
+
+set -e
+
+# Load .env if present (check current dir, ~/.hummingbot/, ~/)
+for f in .env ~/.hummingbot/.env ~/.env; do [ -f "$f" ] && source "$f" && break; done
+API_URL="${API_URL:-http://localhost:8000}"
+API_USER="${API_USER:-admin}"
+API_PASS="${API_PASS:-admin}"
+
+ACCOUNT=""
+CONNECTOR=""
+REFRESH="false"
+SKIP_GATEWAY="false"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --account) ACCOUNT="$2"; shift 2 ;;
+        --connector) CONNECTOR="$2"; shift 2 ;;
+        --refresh) REFRESH="true"; shift ;;
+        --skip-gateway) SKIP_GATEWAY="true"; shift ;;
+        --api-url) API_URL="$2"; shift 2 ;;
+        --api-user) API_USER="$2"; shift 2 ;;
+        --api-pass) API_PASS="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+# Build request body
+REQUEST=$(jq -n \
+    --argjson refresh "$REFRESH" \
+    --argjson skip_gateway "$SKIP_GATEWAY" \
+    '{refresh: $refresh, skip_gateway: $skip_gateway}')
+
+# Add optional filters
+if [ -n "$ACCOUNT" ]; then
+    REQUEST=$(echo "$REQUEST" | jq --arg acc "$ACCOUNT" '. + {account_names: [$acc]}')
+fi
+
+if [ -n "$CONNECTOR" ]; then
+    REQUEST=$(echo "$REQUEST" | jq --arg conn "$CONNECTOR" '. + {connector_names: [$conn]}')
+fi
+
+# Fetch portfolio state
+RESPONSE=$(curl -s -X POST \
+    -u "$API_USER:$API_PASS" \
+    -H "Content-Type: application/json" \
+    -d "$REQUEST" \
+    "$API_URL/portfolio/state")
+
+# Check for error
+if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then
+    echo "{\"error\": \"Failed to get portfolio state\", \"detail\": $RESPONSE}"
+    exit 1
+fi
+
+# Calculate total value from response
+# Response format: {account: {connector: [{token, units, price, value, available_units}]}}
+TOTAL_VALUE=$(echo "$RESPONSE" | jq '[.. | objects | .value? // 0 | select(. != null and . != 0)] | add // 0')
+
+# Format balances for easy reading
+BALANCES=$(echo "$RESPONSE" | jq '
+    [to_entries[] |
+        {
+            account: .key,
+            connectors: [.value | to_entries[] |
+                {
+                    connector: .key,
+                    tokens: [.value[] |
+                        {
+                            token: .token,
+                            units: .units,
+                            available: .available_units,
+                            price: .price,
+                            value: .value
+                        }
+                    ] | sort_by(-.value)
+                }
+            ]
+        }
+    ]
+')
+
+cat << EOF
+{
+    "portfolio_state": $RESPONSE,
+    "summary": {
+        "total_value_usd": $TOTAL_VALUE,
+        "accounts": $(echo "$RESPONSE" | jq 'keys')
+    },
+    "balances": $BALANCES
+}
+EOF

package/skills.json

@@ -8,7 +8,7 @@
     {
       "id": "hummingbot-api-setup",
       "name": "hummingbot-api-setup",
-      "description": "Deploy Hummingbot infrastructure (Docker, API server, Gateway)",
+      "description": "Deploy Hummingbot API infrastructure",
       "category": "infrastructure",
       "triggers": ["install hummingbot", "setup trading", "deploy api", "docker setup"],
       "path": "skills/hummingbot-api-setup",
@@ -18,12 +18,13 @@
         "by_agent": {}
       },
       "first_seen": "2026-01-26T00:00:00Z",
-      "status": "active"
+      "status": "active",
+      "creatorGithubHandle": "david-hummingbot"
     },
     {
       "id": "keys-manager",
       "name": "keys-manager",
-      "description": "Manage exchange API credentials with progressive disclosure",
+      "description": "Manage spot and perpetual exchange API keys",
       "category": "configuration",
       "triggers": ["add api key", "configure exchange", "setup binance", "add credentials"],
       "path": "skills/keys-manager",
@@ -33,7 +34,8 @@
         "by_agent": {}
       },
       "first_seen": "2026-01-26T00:00:00Z",
-      "status": "active"
+      "status": "active",
+      "creatorGithubHandle": "cardosofede"
     },
     {
       "id": "executor-creator",
@@ -48,7 +50,8 @@
         "by_agent": {}
       },
       "first_seen": "2026-01-26T00:00:00Z",
-      "status": "active"
+      "status": "active",
+      "creatorGithubHandle": "cardosofede"
     },
     {
       "id": "candles-feed",
@@ -63,7 +66,24 @@
         "by_agent": {}
       },
       "first_seen": "2026-01-26T00:00:00Z",
-      "status": "active"
+      "status": "active",
+      "creatorGithubHandle": "fengtality"
+    },
+    {
+      "id": "portfolio",
+      "name": "portfolio",
+      "description": "View portfolio balances, positions, and history across all connected exchanges",
+      "category": "data",
+      "triggers": ["check balance", "portfolio", "show positions", "account balance", "my balance"],
+      "path": "skills/portfolio",
+      "installs": {
+        "total": 0,
+        "weekly": 0,
+        "by_agent": {}
+      },
+      "first_seen": "2026-01-29T00:00:00Z",
+      "status": "active",
+      "creatorGithubHandle": "fengtality"
     },
     {
       "id": "spot-connector-tester",

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

@@ -1,92 +0,0 @@
-#!/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