@hummingbot/skills 1.0.0 → 1.0.5

package/README.md

@@ -32,32 +32,33 @@ After installing, ask your AI agent:
 | [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 |
+| [portfolio](./skills/portfolio/) | View balances and positions across exchanges |
 
 ## Prerequisites
 
-Skills interact with the Hummingbot API server:
-- **URL**: `http://localhost:8000`
-- **Credentials**: `admin:admin`
-- **Docs**: `http://localhost:8000/docs`
+Skills interact with the Hummingbot API server. Use the `hummingbot-api-setup` skill to deploy it.
 
-Use the `hummingbot-api-setup` skill to deploy the API server.
+Configure credentials via `.env` file (see `.env.example`):
+```bash
+API_URL=http://localhost:8000
+API_USER=admin
+API_PASS=admin
+```
+
+API docs available at `http://localhost:8000/docs`.
 
 ## 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)
+├── skills/                     # Skill definitions (SKILL.md + scripts/)
+├── app/                        # Next.js webapp (skills.hummingbot.org)
+├── skills.json                 # Skill metadata
+└── .env.example                # API configuration template
 ```
 
 ## Links
 
+- [Skills Webapp](https://skills.hummingbot.org)
 - [Hummingbot](https://hummingbot.org)
-- [skills.sh](https://skills.sh)
 - [Agent Skills Spec](https://agentskills.io)

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@hummingbot/skills",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "AI agent skills for Hummingbot algorithmic trading infrastructure",
+  "scripts": {
+    "build": "cd app && npm run build",
+    "vercel-build": "cd app && npm run build"
+  },
   "keywords": [
     "hummingbot",
     "trading",

package/skills/candles-feed/SKILL.md

@@ -2,9 +2,10 @@
 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
+creator-github-handle: fengtality
 ---
 
-# Hummingbot Candles Skill
+# candles-feed
 
 This skill fetches candlestick (OHLCV) data from exchanges and calculates technical indicators. It provides the data foundation for strategy development and market analysis.
 

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

package/skills/executor-creator/SKILL.md

@@ -2,9 +2,10 @@
 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
+creator-github-handle: cardosofede
 ---
 
-# Hummingbot Executors Skill
+# executor-creator
 
 This skill manages **executors** - lightweight trading components that run directly via the Hummingbot API. Executors are the recommended starting point for new users.
 
@@ -75,14 +76,29 @@ Automated grid trading with multiple buy/sell levels:
 ./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"
+    "side": "BUY",
+    "start_price": "81645",
+    "end_price": "84944",
+    "limit_price": "78347",
+    "total_amount_quote": "100",
+    "leverage": 10,
+    "max_open_orders": 5,
+    "triple_barrier_config": {
+        "stop_loss": 0.05,
+        "take_profit": 0.03,
+        "time_limit": 86400
+    }
 }'
 ```
 
+Grid executor parameters:
+- `start_price`: Price where grid begins (e.g., -1% below current)
+- `end_price`: Price where grid ends / take profit level (e.g., +3% above current)
+- `limit_price`: Stop loss price level (e.g., -5% below current)
+- `total_amount_quote`: Total capital in quote currency (USDT)
+- `leverage`: Position leverage (default: 20)
+- `max_open_orders`: Maximum concurrent orders (default: 5)
+
 ### 3. DCA Executor
 
 Dollar-cost averaging with multiple entry points:
@@ -202,6 +218,30 @@ The position exits when ANY barrier is hit first.
 | `/executors/{id}/stop` | POST | Stop executor |
 | `/executors/positions/summary` | GET | Get held positions |
 
+## API Quirks
+
+The scripts handle these API requirements automatically:
+
+| Issue | Detail | Script Handling |
+|-------|--------|-----------------|
+| **Trailing slash** | POST `/executors/` requires trailing slash | Scripts add it automatically |
+| **Side as numeric** | API requires `1` for BUY, `2` for SELL | Scripts convert "BUY"/"SELL" strings |
+| **executor_config wrapper** | Config must be wrapped in `executor_config` field | Scripts wrap automatically |
+
+If calling the API directly:
+```bash
+curl -X POST -u admin:admin \
+  -H "Content-Type: application/json" \
+  "http://localhost:8000/executors/" \
+  -d '{
+    "executor_config": {
+        "type": "grid_executor",
+        "side": 1,
+        ...
+    }
+}'
+```
+
 ## Error Handling
 
 | Error | Cause | Solution |
@@ -210,3 +250,5 @@ The position exits when ANY barrier is hit first.
 | "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 |
+| "Input should be 1, 2 or 3" | Side must be numeric | Use 1 for BUY, 2 for SELL (scripts handle this) |
+| "307 Temporary Redirect" | Missing trailing slash | Add `/` to endpoint URL |

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"
@@ -62,18 +64,25 @@ else
     CONFIG=$(echo "$CONFIG" | jq --arg type "$EXECUTOR_TYPE" '. + {type: $type}')
 fi
 
+# Convert side from string to numeric (API requires: 1=BUY, 2=SELL)
+CONFIG=$(echo "$CONFIG" | jq '
+    if .side == "BUY" or .side == "buy" then .side = 1
+    elif .side == "SELL" or .side == "sell" then .side = 2
+    else . end
+')
+
 # Build request
 REQUEST=$(jq -n \
     --argjson config "$CONFIG" \
     --arg account "$ACCOUNT" \
     '{executor_config: $config, account_name: $account}')
 
-# Create executor
+# Create executor (note: trailing slash required)
 RESPONSE=$(curl -s -X POST \
     -u "$API_USER:$API_PASS" \
     -H "Content-Type: application/json" \
     -d "$REQUEST" \
-    "$API_URL/executors")
+    "$API_URL/executors/")
 
 # Check for error
 if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -4,6 +4,8 @@
 
 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}"

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

@@ -13,6 +13,8 @@
 
 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}"
@@ -117,11 +119,18 @@ EOF
     "type": "grid_executor",
     "connector_name": "hyperliquid_perpetual",
     "trading_pair": "BTC-USD",
-    "start_price": "80000",
-    "end_price": "90000",
-    "total_amount_quote": "1000",
-    "total_levels": 10,
-    "side": "BUY"
+    "side": "BUY",
+    "start_price": "81645",
+    "end_price": "84944",
+    "limit_price": "78347",
+    "total_amount_quote": "100",
+    "leverage": 10,
+    "max_open_orders": 5,
+    "triple_barrier_config": {
+        "stop_loss": 0.05,
+        "take_profit": 0.03,
+        "time_limit": 86400
+    }
 }'
         elif [ "$EXECUTOR_TYPE" = "dca_executor" ]; then
             EXAMPLE_CONFIG='{
@@ -156,18 +165,25 @@ EOF
         # Ensure type is in the config
         CONFIG_WITH_TYPE=$(echo "$CONFIG" | jq --arg type "$EXECUTOR_TYPE" '. + {type: $type}')
 
+        # Convert side from string to numeric (API requires: 1=BUY, 2=SELL)
+        CONFIG_WITH_TYPE=$(echo "$CONFIG_WITH_TYPE" | jq '
+            if .side == "BUY" or .side == "buy" then .side = 1
+            elif .side == "SELL" or .side == "sell" then .side = 2
+            else . end
+        ')
+
         # Build request
         REQUEST=$(jq -n \
             --argjson config "$CONFIG_WITH_TYPE" \
             --arg account "$ACCOUNT" \
             '{executor_config: $config, account_name: $account}')
 
-        # Create executor
+        # Create executor (note: trailing slash required)
         RESPONSE=$(curl -s -X POST \
             -u "$API_USER:$API_PASS" \
             -H "Content-Type: application/json" \
             -d "$REQUEST" \
-            "$API_URL/executors")
+            "$API_URL/executors/")
 
         if echo "$RESPONSE" | jq -e '.detail' > /dev/null 2>&1; then
             echo "{\"error\": \"Failed to create executor\", \"detail\": $RESPONSE}"

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

@@ -4,6 +4,8 @@
 
 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}"