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

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.

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

./scripts/setup_executor.sh

Shows all executor types with descriptions and current summary.

Step 2: Get Config Schema

./scripts/setup_executor.sh --type position_executor

Shows required fields and example configuration.

Step 3: Create Executor

./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

./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:

./scripts/setup_executor.sh --type grid_executor --config '{
    "connector_name": "hyperliquid_perpetual",
    "trading_pair": "BTC-USD",
    "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:

./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

./scripts/list_executors.sh [--status RUNNING] [--connector hyperliquid_perpetual]

Get Executor Details

./scripts/get_executor.sh --id <executor_id>

Stop Executor

# 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

./scripts/get_executors_summary.sh

Manage Held Positions

# 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

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

API Quirks

The scripts handle these API requirements automatically:

If calling the API directly:

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