Skip to content
Terminal

Hummingbot

Who it is for

Use this guide if you run Hummingbot and you want your bot to receive the alerts you set in Terminal.

What Terminal sends

The script reads your alerts from the events feed, GET /v1/events, and publishes each one to your Hummingbot MQTT broker. An API key is a secret your software sends so Terminal knows which account is asking. The published payload is the Terminal event JSON, with the same fields the feed returned. The script does not wrap it and does not add an order.

Terminal never chooses a side, an amount, or a trade. You type every trade field in your own bot. Your bot decides. The script does not place an order, and it does not call a trading API.

Create an API key

Open Settings, then API keys.

The page title is API keys. The intro says: "An API key lets your own software or bot read your alerts and receipts, and change your alerts if you allow it. Keep it secret, like a password."

  1. If you have no key yet, the page says "No API keys yet. Create one to connect your software."
  2. Choose Create API key.
  3. Name is the label. The hint says: "Where you will use it, such as "Freqtrade server"." Type the name of the machine that will run this script.
  4. What it can do lists the scopes. Read alerts, rules and receipts is on, and it stays on. That read scope is enough for this script.
  5. Choose Create API key. The page says "Copy your API key now" and "This is the only time we show the whole key. Store it somewhere safe. If you lose it, revoke it and create a new one."

Put the key in TERMINAL_API_KEY. The script reads every secret from the environment. It does not write the API key, a broker password, or either value into the cursor file, the log, or the URL.

Free includes 1 API key. This script reads the events feed. Webhooks are a separate limit, under Limits below.

Install and run

Python 3.10 or newer. Download terminal_bridge.py. The README has every detail. The file is MIT licensed. A live run needs the MQTT client:

pip install paho-mqtt

A dry run does not import that package. If it is missing when you publish for real, the script says to install it and stops.

Set the key and the topic, then start the script:

export TERMINAL_API_KEY="your API key"
export MQTT_TOPIC="hbot/your-instance-id/external/event/terminal"
python3 terminal_bridge.py

Replace {instance_id} with the instance_id in the bot's conf_client.yml. A live run stops while MQTT_TOPIC still contains {instance_id}. Do not put + or # in the topic. Those are for subscribers.

The script asks GET /v1/events and leaves the request open for up to 25 seconds when no alert is ready. That wait is a long-poll: the request stays open until an alert is ready or the wait ends. When the answer says more events are ready, it asks again at once. It stores next_cursor and sends that cursor on the next request, including after a restart. A cursor is the saved place in the feed.

Start the Hummingbot MQTT bridge before you expect events. Hummingbot's broker page is Bot orchestration. The client source subscribes to {namespace}/{instance_id}/external/event/# in mqtt.py. The namespace, host, and port defaults are in client_config_map.py: namespace hbot, host localhost, port 1883. mqtt_external_events defaults to on. mqtt_autostart defaults to off, so start the bridge in the client, or turn autostart on.

The last segment of the default topic is terminal. That is the event name Hummingbot derives from the topic. Hummingbot's external-event listener keeps timestamp, sequence, type, and data, and drops other fields. A script that needs the whole event should listen with ExternalTopicFactory. The example script comments a different topic shape in external_events_example.py. This bridge follows mqtt.py.

On HTTP 429 the script waits the Retry-After seconds, at least 1 and at most 3600, then asks again. A 5xx answer, a lost connection or a cut-off answer waits 5 seconds, then 10, 20, 40 and 60 while the trouble lasts, or the Retry-After seconds when they are longer. An empty answer that comes back at once waits 1 second. It does not follow redirects. It stops on 401, 403 and any other answer it cannot use, and before the first request when the key has a space or a line break in it.

The broker publish uses QoS 1. The script waits for the broker to accept the message before it stores the cursor. While the broker refuses, the script keeps the answer and publishes it again after 5, 10, 20, 40 and then 60 seconds. It does not ask the feed again meanwhile, because an answer with events counts as an API call.

Environment variables

A TERMINAL_API_URL that already ends in /v1 or /v1/events works too.

The cursor file stores one line, the opaque next_cursor, which starts with c1_. The API key is not in that file. A file that holds anything else stops the script before the first request. Delete it to start again from TERMINAL_START.

Replay a recorded file

Example. These are not live prices.

python3 terminal_bridge.py --dry-run fixtures/events.jsonl

Run that command from the directory that contains terminal_bridge.py and fixtures/events.jsonl. The script prints each event it would publish, one JSON object per line. It does not open a network connection and it does not load paho-mqtt. Pass --cursor-file to choose the cursor file.

Send a test

This script does not use a webhook, so there is no Send a test for the bridge. The dry run above replays a recorded file on your machine.

A webhook is separate. If you add one for other software, open Alerts and quiet hours. The form title is Your bot or software. Message format for software you write is Terminal format (JSON). The hint says: "The alert with its numbers, their sources and times. For software you write."

The row's button is Send a test. For a bot format, the warning says: "A test sends this exact body. If your bot trades on it, switch the bot to paper trading or turn it off first."

Check the box "I understand that a test can make my bot act." Send a test stays off until that box is checked.

A Terminal format webhook stays Not tested yet until a test your receiver accepts. The page says: "Not tested yet. Send a test your receiver accepts to turn this on."

Each alert is sent once

On the events feed, the script stores the cursor only after the broker accepts every event in that answer. An event id already published in this run is dropped.

A webhook to a bot is sent once. The form says: "Each alert goes to your bot once. If your bot does not answer in time, we do not send it again, so one alert does not reach your bot twice. Missed alerts are in the delivery log."

The log's short line for that miss is "No answer from your receiver. Not sent again."

Check the delivery log

The cursor file is how you see where the feed left off. Delete it to start again from TERMINAL_START.

Webhook deliveries are a different list. Open the alert from Today. The alert page has a Delivery list. That list is the delivery log. Each line names where the alert went and the time.

On Alerts and quiet hours, a webhook row shows Last alert sent and Last sequence number. A sequence number grows by one for each alert sent to that webhook.

Limits

Free includes 1 API key. The events feed uses that key.

Webhooks for your software are part of Pro. Signed webhooks are on Pro. Pro includes 5 webhooks. Free and Trader include none. Remove one first when you already have 5. You can get Pro only while paid plans are open. Plans says whether they are.

If you leave Pro, the webhooks stay on the page and send nothing. The events feed keeps working with your API key.

Create a free account

All developer pages

Terminal reports market events for conditions you set. It does not tell you to buy, sell, or hold, and it does not place trades.