docs › Telegram (your own bot)

Telegram (your own bot)

Alerts on your phone, pause and stop from anywhere, and one-tap approvals for autotrade entries, through a bot you create. Nothing is hosted by us. Paper first, experimental, not financial advice.

What it is#

The autotrade runner can talk to your own Telegram bot. You create the bot, you give its token to dexterm on your own computer, and the runner polls Telegram from your computer while it runs. There is no dexterm server in between: nothing is hosted by us, nobody else holds your token, and nothing trades for anyone but you.

It does three things, each one a tier you grant when you pair:

Notify: candidates found, entries and exits, a PnL card for every closed trade, halts and guards, spend warnings and a daily summary.
Control: /status, /positions, /pause, /resume, /kill, /flatten, /strategies, /use and /approvals on. Chat can always make things safer and never less safe.
Approve: every new entry waits for your tap, with [Approve] [Half size] [Skip] buttons. Only a button approves; a typed message never does.

It runs on paper: an approved entry fills on the paper book, with no key, wallet or signer anywhere. This is also dexterm's part in live trading: dexterm holds no key, and live trades happen in a separate Telegram trading bot of your choice, which holds its own wallet. dexterm sends the alerts and run control to your chat; in this version it does not place orders in that trading bot for you. Experimental, not financial advice.

Set it up#

In Telegram, open @BotFather, send /newbot, pick a name, and copy the token it gives you.
On your computer, run:

dexterm telegram setup

Paste the token at the prompt (nothing is shown while you type, and a token passed as an argument is refused, so it never lands in your shell history). dexterm checks it with Telegram and prints the bot's username, then stores the token in your macOS keychain, the system keyring on Linux (libsecret), or a file only you can read under ~/.dexterm/secrets/ when neither exists. It is never written to a config file, a log, the command line or the environment. Settings live in ~/.dexterm/connectors.json, which holds no secret.

Setup first checks that nobody else is reading your bot (a webhook on it, or another program polling it). If anything is, it refuses to pair. Otherwise it shows a 6-digit pairing code on your screen, valid for 5 minutes. Open a private chat with your bot from your own account and send /pair and the code. Your computer then shows the account the code came from, its @username and id, and asks you to confirm it with y. Only then is that account in that chat the only one the bot answers. The code travels through Telegram, so this check is what stops someone who has your token: if another program polls the bot while the code is open, pairing stops, and an account you do not recognise gets n.

Pair again any time with dexterm telegram pair (add --tiers notify,control to leave approvals out). Check what is set up with dexterm telegram status, and send one test message with dexterm telegram test.

Start the runner as usual. When a chat is paired, the bot comes up with it:

dexterm autotrade run moonbag --paper

--no-telegram keeps it off for one run.

Turn on Telegram's two-step verification for your account. Messages are not end-to-end encrypted: the bot never sends keys, seed phrases, wallet addresses or balances, and it never asks for them. Anything that asks you for those is not dexterm.

Notify: what reaches your phone#

Every message leads with its badge (PAPER today) and is plain text: token names are shown as quoted data, passed through the same prompt firewall the analyst uses, with links, addresses, commands and mentions made inert.

event	default	what it says
candidates found	a digest every 15 minutes	symbol, short mint, the rules that matched
entry and exit	on	size in $ and as % of the book, price, profile, the exit reason, your agent's reason (quoted)
trade closed	on	the PnL card image and one line: P/L in % and $, the exit, how long it was held
halts and guards	on	the state, the reason, and what clears it
spend and usage	on	once a day at 80 % of the day's model spend cap, or of a Claude usage window
daily summary	on, 21:00	trades, wins and losses, the day's P/L in %, open positions, spend, the runner state, approvals

Shown: the badge, the symbol, a short mint (abcd…wxyz), the strategy and its short hash, each trade's size and its share of the book. Never shown: keys, the bot token, wallet addresses, wallet balances or the absolute book, file paths. An exit reason or a halt reason that quotes a path, an API key, a long hex value or a keypair shows [path], [key] or [hex] instead.

Change it locally: dexterm telegram notify candidates digest|each|off, dexterm telegram notify entries|closes|halts|spend|daily on|off, dexterm telegram set summary-at 21:00 (or off), and dexterm telegram set quiet 23:00-07:00 (quiet hours hold the notify-only lines; halts, proposals and replies still go). Above 20 messages a minute the bot switches to digests on its own.

Control: the commands#

The list is closed. Anything else gets the help text.

command	what it does	from chat
`/status`	the runner state, strategy, open positions, the day's P/L %, spend, approvals	always
`/positions`	each open position with a [Sell] button	always
`/pause`	no new entries; exits keep running	always
`/resume`	lifts a pause	only a pause: never a kill, the panic switch, a loss-limit halt or a guard; those clear on your computer
`/kill` (or `/stop`)	the same as `dexterm autotrade stop`: no new entries, sessions closed, pending orders dropped, exits keep running until nothing is held	always
`/flatten`	stop, then sell every position at its next tick	after a [Yes, flatten] button
`/strategies`	your validated strategies and the presets, marked when `/use` may pick them	always
`/use <strategy>`	switch to another strategy	only to one that is equal or tighter than the running one, after a [Yes, switch] button. Any change dexterm cannot rank (a field with no safety rule, or a value it cannot compare) counts as looser, and so do a bigger bankroll and a dip-buying ladder. New entries stop at once; the new strategy starts once the open positions have closed. It never changes paper or live
`/approvals on`	every new entry waits for your tap	always. `off` is local only: `dexterm telegram approvals off`

Never from chat, because no such command exists: live mode, looser caps or strategies, approvals off, resuming after a kill or the panic switch, moving funds.

Chat writes the same control file dexterm autotrade stop and the AUTOTRADE screen write, so it is a remote control for the runner on your computer and adds no way around its limits. Commands are limited to 10 a minute; /kill, /stop, /pause and /flatten are never limited. A command sent while nothing was polling is not acted on when the bot comes back. Commands count only in your private chat, and a forwarded message or one sent through an inline bot is never a command.

Approve: one-tap entries#

Approvals are on for a strategy whose entry.decide is "agent+approve", and for every strategy after /approvals on (or dexterm telegram approvals on). Your agent still decides and your strategy still clamps the size; the entry then becomes a proposal instead of an order:

PAPER · PROPOSAL · moonbag v1.0.0 (67fc4c95)
token "SYM" abcd…wxyz
buy $20.00 (2.0% of book) @ 0.0001645 · liq $36.6K · impact ~0.40%
plan: moonbag: cost back at +100%, then a 55% bag trail, out after 7 days, no hard stop
why (the agent's words, unverified): "Fresh pair 34 min old, buyers 1.6x sellers."
expires in 90 s · #k3Jd9aQx
Only these buttons approve. Replies are ignored.
[Approve] [Half size] [Skip]

No answer is a skip. A proposal expires after 90 seconds (set 60 to 120 with dexterm telegram set expiry), on your computer's clock. There is no auto-approve.
[Half size] only ever halves. [Skip] skips.
The price is checked again at your tap. If it moved more than 3 % (never more than the strategy's own slippage), the liquidity fell more than 10 %, or the impact would pass the strategy's cap, the card is re-quoted with fresh numbers and new buttons and you confirm once more. A second move is a skip.
Your limits are checked again at your tap, against the book as it is then: the size can shrink, or the entry is refused.
One tap, once. Every button is bound to a one-time code, the proposal's exact numbers, its expiry, your account and your private chat. A double tap, a second device or an old button gets "Already handled"; a forwarded card tapped by someone else, or in a group, is refused.
A kill, a pause or a halt cancels every open proposal and removes its buttons. If the runner restarts, open proposals expire; they are never brought back.
Exits never wait for chat. Stops, take-profits, trails and rug exits run on their own, and a [Sell] on /positions only ever sells.
At most as many proposals are open at once as the strategy allows sessions; the rest are skipped and counted.

The order then goes through the paper book with a single-use approval for exactly that order (bound to its hash and the proposal): a different order, a different coin, a bigger size or a second use is refused.

If something goes wrong#

Telegram is down, or a message cannot be sent: the proposal is a skip. Notifications retry. The runner never waits on chat, and your exits are unaffected.
Someone else uses your token (a webhook appears on the bot, or another program polls it): the bot stops every approval, you are warned on your computer, and every local control keeps working (dexterm autotrade stop, the AUTOTRADE screen, dexterm wallet panic). Messages from accounts that are not paired get no answer; five in an hour raise a "possible token leak" warning on your computer.
Revoke it: dexterm telegram revoke removes the token from your computer and forgets every paired chat. If the token may have leaked, also send /revoke to @BotFather for that bot and run setup again.

The record#

Every inbound update (the sender, the chat, the command or button; free text only as a length and a hash), every message sent, every proposal state and every check of a tap is written to ~/.dexterm/autotrade/chat/<day>.jsonl, hash-chained like the run files. The token, raw one-time codes and balances are never written. dexterm telegram audit --verify recomputes each day's chain and names the first edited, missing or reordered line. The run file records each approval request, the answer and the fill it led to, and anchors the chat record (its day file, head and length) when a run starts and ends. The check compares every anchor, so a day file that was cut short, deleted or rewritten after a run anchored it does not verify. Lines written after the last run ended are not anchored yet.

What it will not do#

Run anywhere but your computer, or on a shared or hosted bot.
Post proposals to a group or a channel: approvals work only in your private chat, and relaying AI trade calls to an audience is something we tell you not to do.
Read a typed message as a trade, by a parser or by a model.
Make anything less safe from chat.
Hold or ask for your keys, seed phrase or wallet.
Place an order in a trading bot, or sign or send a transaction.