home / skills / hummingbot / skills / hummingbot-heartbeat

hummingbot-heartbeat skill

safe

This skill delivers hourly Hummingbot status updates to your chat by reporting API health, gateway, bots, executors, and portfolio balances.

npx playbooks add skill hummingbot/skills --skill hummingbot-heartbeat

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.6 KB

---
name: hummingbot-heartbeat
description: OpenClaw cron job that delivers hourly Hummingbot status updates to your chat — API health, Gateway container, active bots/controllers, executors, and portfolio balances.
---

# hummingbot-heartbeat

An OpenClaw cron skill that runs every hour and delivers a formatted Hummingbot status report to your connected chat channel (Telegram, Discord, etc.). Covers API health, Gateway container, active bots/controllers, executors, and portfolio balances.

## Installation

```bash
clawhub install hummingbot-heartbeat
```

Or manually clone into your skills directory.

## Quick Start

### 1. Set up the OpenClaw cron job

Ask your OpenClaw agent:

> "Set up the hummingbot-heartbeat cron job"

The agent will resolve the skill path and register it with `openclaw cron`. Or do it manually:

```bash
# Replace <SKILL_PATH> with the actual installed path
openclaw cron add \
  --name "hummingbot-heartbeat" \
  --description "Hourly Hummingbot status check" \
  --every 1h \
  --announce \
  --channel telegram \
  --message "Run this and send output verbatim: python3 <SKILL_PATH>/scripts/bot_status.py"
```

### 2. Run manually (debug)

```bash
python3 scripts/bot_status.py
python3 scripts/bot_status.py --json
```

## Configuration

Set via environment variables or a `.env` file in the skill directory:

```bash
# .env (optional — defaults shown)
HUMMINGBOT_API_URL=http://localhost:8000
API_USER=admin
API_PASS=admin
```

| Variable | Default | Description |
|----------|---------|-------------|
| `HUMMINGBOT_API_URL` | `http://localhost:8000` | Hummingbot API base URL |
| `API_USER` | `admin` | API username |
| `API_PASS` | `admin` | API password |

## Requirements

- Python 3.9+
- Hummingbot API running (see `hummingbot-deploy` skill)
- Docker (optional — Gateway status check skipped if Docker unavailable)

## Sample Output

```
🤖 Hummingbot Status — Feb 28, 2026 09:06 AM

**Infrastructure**
  API:     ✅ Up (v1.0.1)
  Gateway: ✅ Up 17 hours

**Active Bots:** none

**Active Executors:** none

**Portfolio** (total: $187.23)
  Token           Units       Price      Value
  ------------ ----------- ---------- ----------
  SOL            2.0639    $81.4996    $168.20
  USDC          19.0286     $1.0000     $19.03
```

## What It Checks

| Check | Endpoint | Notes |
|-------|----------|-------|
| API health | `GET /` | Returns version |
| Gateway | `docker ps \| grep gateway` | Skipped if Docker unavailable |
| Active bots | `GET /bot-orchestration/status` | Lists controller configs |
| Active executors | `POST /executors/search` | Filters out CLOSED/FAILED |
| Portfolio | `POST /portfolio/history` | Latest balances with prices |

Overview

This skill delivers hourly Hummingbot status updates to your connected chat channel. It runs as an OpenClaw cron job and compiles API health, Gateway container state, active bots and executors, and portfolio balances into a concise report. Use it to monitor trading infrastructure proactively and surface issues before they impact operations.

How this skill works

The skill runs a scheduled job (default every hour) that queries the Hummingbot API and optional Docker host. It checks the root API for version and uptime, inspects the Gateway container if Docker is available, lists active bot controllers and executors, and requests the latest portfolio balances and prices. The script formats the results and sends a textual report to your configured chat channel (Telegram, Discord, etc.).

When to use it

Continuous monitoring of Hummingbot deployments with automated hourly reports
On-call rotations where quick infrastructure snapshots are needed
Pre-trading checks to confirm API and Gateway availability
Debugging or auditing active bots, executors, and account balances
Integrating status alerts into team chat for operational transparency

Best practices

Run the cron job via OpenClaw to handle scheduling and channel delivery reliably
Store HUMMINGBOT_API_URL, API_USER, API_PASS in environment variables or a .env file
Enable Docker on the host if you want Gateway container checks included
Use the --json flag for machine-readable output when piping into other tools
Limit chat channel recipients to operational staff to avoid alert fatigue

Example use cases

Hourly delivery of system health to a Telegram ops group to quickly spot API failures
Daily audit of active bots and executors to detect orphaned or stuck jobs
Portfolio snapshot posted before markets open to verify balances and pricing
Automated troubleshooting: combine JSON output with logging to trace intermittent issues

FAQ

How do I run the check manually for debugging?

Run python3 scripts/bot_status.py or python3 scripts/bot_status.py --json in the skill directory.

What environment variables are required?

Set HUMMINGBOT_API_URL, API_USER, and API_PASS. Defaults are http://localhost:8000, admin, admin.

Will Gateway checks work without Docker?

No. Gateway container status is skipped if Docker is not available on the host.