Freqtrade

Who it is for

Use this guide if you run Freqtrade and you want a strategy to read the alerts you set in Terminal.

What Terminal sends

The helper reads your alerts from the events feed, GET /v1/events. An API key is a secret your software sends so Terminal knows which account is asking. Each event is an alert you set, with the price, its source, and its time.

Terminal never chooses a side, an amount, or a trade. You type every trade field in your own bot. Your strategy decides. The helper does not place an order.

The helper does not invent past alerts. A backtest does not call the API, and the informational columns stay empty there.

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"."
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 helper.
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 the environment variable below. The helper sends it only as Authorization: Bearer. It does not write the key into a URL, a query string, or a log line.

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

Install and run

Python 3.10 or newer. The helper uses the standard library only. You do not install a package for it. Freqtrade is your own install.

Download terminal_feed.py and example_strategy.py, and copy both into your Freqtrade user_data/strategies/ folder. Freqtrade loads the strategy by its class name. The README has every detail. The files are MIT licensed.

export TERMINAL_API_KEY="the API key from Settings"
freqtrade trade --strategy TerminalAlertsStrategy

The helper starts in bot_start, and only when Freqtrade is in live or dry-run mode.

Freqtrade describes those callbacks in its own docs: strategy callbacks and strategy customization.

Environment variables

Read the key from the environment. Do not put it in the strategy file.

• Name: TERMINAL_API_KEY. Required: yes, for live reading. Meaning: Your API key. The helper sends it only as Authorization: Bearer.
• Name: TERMINAL_API_URL. Required: no. Meaning: The site origin. Defaults to https://terminal.tokensmarketcap.com. The helper requests <origin>/v1/events. A value that already ends in /v1 or /v1/events works too.
• Name: TERMINAL_CURSOR_PATH. Required: no. Meaning: File for the saved cursor. Defaults to terminal-events.cursor in the current directory when the feed is running. A dry run writes a cursor file only when this variable is set.

Do not put the key in TERMINAL_API_URL. The helper does not follow a redirect, so the key stays on the host you set.

What the strategy shows

A background thread requests GET /v1/events?wait=25. A long-poll is a request that stays open until an alert is ready or the wait ends. With no saved cursor, the first request sends start=latest, so you get alerts recorded from then on. A cursor is the saved place in the feed. The helper stores next_cursor and sends it on the next request. Do not commit that file. Delete it to start again from the newest alert.

recent(symbol, minutes) returns the kept events for that coin whose fired_at is within the last minutes minutes, oldest first. The match ignores letter case. symbol_from_pair turns a Freqtrade pair into that symbol: SOL/USDT and SOL/USDT:USDT both become SOL.

populate_indicators writes two informational columns on the latest row. Older rows stay at 0 and blank.

• terminal_alert_count is how many alerts for that coin fired in the last terminal_recent_minutes (60, until you change it).
• terminal_alert_headline is the headline of the latest of those alerts.

populate_entry_trend and populate_exit_trend leave the entry and exit columns at 0, next to the comment # your own conditions here. Write your conditions there. Terminal does not choose an entry or an exit for you.

The file sets timeframe, minimal_roi, and stoploss because Freqtrade requires them before it will load a strategy. Terminal does not choose them for you: minimal_roi is empty and stoploss is -1.0, a 100% stop, so neither acts. Replace each value with your own. The entry and exit columns stay 0, so the strategy does not open or close a trade until you write a condition.

When the answer says has_more, the helper asks again at once. A lost connection delays an alert. The next request uses the saved cursor. On HTTP 429 the helper waits the Retry-After seconds, from 1 to 120. The helper keeps one request open. Terminal allows two open event requests per API key. It stops, and says why in Freqtrade's log, on a 401 or 403 (the key was refused), on a 400 about the cursor (delete the cursor file), and on another 400 or 404 (check TERMINAL_API_URL).

gap means an alert after your cursor is older than 7 days and is no longer in the feed. The helper logs the gap. Read GET /v1/rules/{id}/record for a rule you still need. The helper does not call that route for you.

Replay a recorded file

Example. These are not live prices.

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

Run that command from the directory that contains terminal_feed.py and fixtures/events.jsonl. It reads the file. It does not call the API, and it does not need an API key.

Send a test

This helper does not use a webhook, so there is no Send a test for the strategy. 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, resume from the saved cursor. The helper drops an event whose id it has already seen.

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 helper's cursor file is how you see where the feed left off. Delete it to start again from the newest alert.

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

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