Multi-Chain Telegram Signal Trading Bot

A self-hosted bot that watches the Telegram groups and channels you choose, picks up token contract addresses the moment they are posted, buys them on Solana, Ethereum, BNB Chain, Arbitrum, Base or Robinhood Chain, and manages every position automatically: tiered take-profit, moonbag, stop loss, trailing stop and time exit.

It runs as one process on your own PC under PM2. There is no database server, no Redis and no Docker: all state lives in JSON files, and wallet keys are encrypted with AES-256-GCM and never leave your machine.

Warning

This bot spends real money on highly speculative tokens called out in public chats. Safety checks remove obvious traps; they do not make trades profitable. Start in dry run, use a fresh wallet, and only fund it with what you can afford to lose.

Features
Supported chains
How it works
Requirements
Installation
Configuration (.env)
Wallets and funding
First run
Using the bot in Telegram
Signal sources: groups and channels
What gets bought: the filter pipeline
Exit strategy
Safety checks
Dashboard (PC and phone)
Running 24/7 with PM2
Going live
Robinhood Chain
Data, backups and security
Troubleshooting
Project structure
Development and tests
Documentation index

1. Features

Signal intake

Reads any group or channel your own Telegram account can see (Telethon userbot), chosen from inside the bot. Nothing is enabled until you switch it on.
Separate Groups and Channels screens with paging, plus /addchannel to join a channel from a link or @username.
Detects EVM (0x…) and Solana addresses, including addresses inside DexScreener / explorer links, and confirms the EVM chain on-chain.
Only trades messages posted after a chat was switched on, and no older than 5 minutes. History, replays and old posts edited later are never bought.
Messages with no token address are dropped before any other work.

Execution

Solana via Jupiter, sent privately through Jito bundles, with a pre-send simulation, a fee reserve and automatic re-routing of oversized transactions.
EVM chains via 1inch (with a key) or direct Uniswap V2-style routers, through private relays (Flashbots Protect, 48 Club) where configured.
Robinhood Chain via Uniswap v3 and v4 (multi-hop, hooked pools, Permit2), whichever quotes better.
Every EVM transaction is executed with eth_call first; a revert is refused for free instead of costing gas.

Position management

Tiered take-profit, moonbag ("sell my cost back at 2x, ride the rest"), stop loss, trailing stop with an arming threshold, and time exit.
Global defaults with per-token overrides; the exit plan is snapshotted into each position at entry.
Sells always use the real on-chain balance, with retry back-off.
/panic turns auto-buy off and exits everything.

Operations

Telegram inline-keyboard UI for every setting; changes are saved to disk immediately and survive restarts.
Live web dashboard on localhost, also openable inside Telegram on your phone through a free Cloudflare tunnel.
Terminal tools: doctor (pre-flight check) and wallet (create / list / export / import).
Atomic JSON storage with automatic .bak recovery and a single-instance lock.

2. Supported chains

Chain	Gas coin	Buys routed through	Private sending	Honeypot simulation
Solana	SOL	Jupiter	Jito bundles	RugCheck
Ethereum	ETH	1inch or Uniswap V2 router	Flashbots Protect	honeypot.is + GoPlus
BNB Chain	BNB	1inch or PancakeSwap	48 Club (optional)	honeypot.is + GoPlus
Arbitrum	ETH	1inch or Uniswap router	optional	honeypot.is + GoPlus
Base	ETH	1inch or Uniswap router	optional	honeypot.is + GoPlus
Robinhood Chain (4663)	ETH	Uniswap v3 + v4	sequencer (FCFS)	GoPlus + round-trip quote

One EVM private key gives you the same address on every EVM chain, but each chain has its own balance. Solana uses a separate key and address.

3. How it works

flowchart LR
    TG[Telegram groups and channels] -->|Telethon userbot| L[Signal listener]
    L -->|address found, chat ON, fresh post| F[Per-user filters]
    F --> Q[(Job queue)]
    Q --> W[Workers / Executor]
    W --> S[Safety checks]
    S --> R{Chain router}
    R --> SOL[Solana: Jupiter + Jito]
    R --> EVM[EVM: 1inch / routers / Uniswap v3-v4]
    W --> D[(data/*.json)]
    P[Price feed: DexScreener / Birdeye] --> PM[Position manager]
    PM -->|TP / SL / trail / time| Q
    W --> UI[Telegram bot + dashboard]

Listener receives every new or edited message from your account.
Messages without a token address are discarded; the rest must come from a chat you switched on and be freshly posted.
Filters run per user: chains, blacklist words, sender whitelist, token blacklist, open-position limit, cooldown.
The executor checks balance, token age, previous trades and safety, then buys and records the position.
The position manager watches prices and queues sells when an exit rule triggers. A reconciler confirms every transaction on-chain and corrects the books if one never lands.

Everything runs as asyncio tasks inside one Python process.

4. Requirements


OS	Windows 10/11 (primary), Linux or macOS
Python	3.11 or newer (verified on 3.14)
Node.js	18 or newer, only for PM2
Telegram	Your normal account, plus a bot created with @BotFather
RPC	An Alchemy API key (free tier works)
Optional	1inch API key, Birdeye API key, Jupiter API key, Cloudflare `cloudflared`

5. Installation

Run each command from the project folder.

Step 1 — Install Python and Node, then check them:

python --version

node --version

Step 2 — Install PM2

npm install -g pm2

Step 3 — Create the virtual environment

python -m venv .venv

.venv/Scripts/python.exe -m pip install -r requirements.txt

On Linux/macOS use .venv/bin/python instead of .venv/Scripts/python.exe everywhere in this document.

Step 4 — Create your config file

cp .env.example .env

Step 5 — Create the data folder

.venv/Scripts/python.exe -m scripts.init_db

Important

Do not keep the project inside a cloud-synced folder (OneDrive, Dropbox, Google Drive). data/ and .env contain your encrypted keys and the key that decrypts them.

Full walkthrough with screenshots-in-text: SETUP.md.

6. Configuration (`.env`)

Open .env in a text editor. Never share or commit this file.

6.1 Required

Variable	How to get it
`MASTER_ENCRYPTION_KEY`	Run `.venv/Scripts/python.exe -m scripts.gen_master_key`. Back it up offline: without it, stored wallet keys cannot be decrypted.
`TELEGRAM_BOT_TOKEN`	Message @BotFather → `/newbot`.
`TELEGRAM_ADMIN_IDS`	Your numeric user ID from @userinfobot. Only these IDs can use the bot.
`TELEGRAM_API_ID`, `TELEGRAM_API_HASH`	https://my.telegram.org → API development tools → create an app.
`TELEGRAM_STRING_SESSION`	Run `.venv/Scripts/python.exe -m scripts.gen_session` and log in with your own account.
`ALCHEMY_API_KEY`	https://dashboard.alchemy.com → create an app → copy the key. One key covers all chains.
`DRY_RUN`	`true` to simulate every order (start here), `false` to trade for real.

Why your own account? A bot account cannot read groups or channels it was not added to. Your account does the reading; the bot account is only the control panel.

6.2 Recommended

Variable	Purpose
`JITO_TIP_LAMPORTS`	Tip that sends Solana swaps privately through Jito (`100000` = 0.0001 SOL; `0` disables).
`FLASHBOTS_PROTECT_RPC`, `BSC_PRIVATE_RPC`, `BASE_PRIVATE_RPC`, `ARBITRUM_PRIVATE_RPC`	Private relays so buys are not sandwiched. `USE_PRIVATE_RPC=false` disables them.
`ONEINCH_API_KEY`	Better EVM routing. Without it, direct router calls are used.
`BIRDEYE_API_KEY`	Faster Solana price stream. Without it, DexScreener polling is used.
`JUPITER_API_KEY`	Paid Jupiter tier (set `JUPITER_API_BASE=https://api.jup.ag/swap/v1`).

6.3 Optional

Variable	Default	Purpose
`RPC_SOLANA` … `RPC_ROBINHOOD`	blank	Force a specific RPC per chain instead of Alchemy.
`ENABLE_UNISWAP_V4`	`true`	Uniswap v4 routing on Robinhood Chain.
`PUBLIC_URL`	blank	A fixed HTTPS address for the dashboard. Not needed with the Cloudflare quick tunnel.
`TUNNEL_METRICS_URL`	`http://127.0.0.1:20241`	Where the bot reads the quick-tunnel address from.
`DASHBOARD_TOKEN`	blank	Secret for opening the dashboard in a normal browser off this PC.
`ALCHEMY_AUTH_TOKEN`, `ALCHEMY_WEBHOOK_SIGNING_KEY`, `WEBHOOK_PUBLIC_URL`	blank	Alchemy Notify webhooks for instant confirmations (a poller confirms without them).
`SIGNAL_SOURCE_CHATS`	blank	Seeds the chat list on the very first run only. Normally you pick chats in the bot.
`DATA_DIR`	`data`	Where JSON state is stored.
`LOG_LEVEL`	`INFO`	`DEBUG` for verbose logs.

6.4 Trading defaults

These seed a new user's settings. After that, change everything in Telegram; the values in .env are not re-applied.

Variable	Default	Meaning
`DEFAULT_BUY_AMOUNT_SOL` / `_ETH` / `_BNB`	`0.1` / `0.001` / `0.05`	Size of each buy in the chain's gas coin.
`DEFAULT_SLIPPAGE_BPS`	`1500`	15% slippage.
`DEFAULT_TP_TIERS`	`100:50,200:50`	Sell 50% at +100%, the rest at +200%.
`DEFAULT_STOP_LOSS_PCT`	`35`	Sell everything at −35%.
`DEFAULT_TRAILING_STOP_PCT`	`20`	Sell 20% below the peak once armed.
`DEFAULT_MAX_HOLD_MINUTES`	`0`	Time exit (0 = off).
`DEFAULT_MIN_TOKEN_AGE_MINUTES`	`2880`	Skip tokens younger than 2 days.
`DEFAULT_MAX_TOKEN_AGE_MINUTES`	`11520`	Skip tokens older than 8 days.

6.5 Verify the configuration

.venv/Scripts/python.exe -m scripts.doctor

It checks the master key, data folder, bot token, Telegram session, every RPC (with chain ID) and your safety settings. Fix anything marked FAIL.

7. Wallets and funding

The bot is non-custodial: it holds its own hot wallets, encrypted in data/wallets.json. Stop the bot before using the wallet tool (only one process may own data/):

pm2 stop mcb

Task	Command
Create an EVM wallet and a Solana wallet	`.venv/Scripts/python.exe -m scripts.wallet create`
Create and also save the keys to a file	`.venv/Scripts/python.exe -m scripts.wallet create --save D:/keys/bot-wallet.txt`
EVM wallet only	`.venv/Scripts/python.exe -m scripts.wallet create --no-solana`
Show addresses and live balances	`.venv/Scripts/python.exe -m scripts.wallet list`
Print one private key	`.venv/Scripts/python.exe -m scripts.wallet export --chain robinhood`
Use an existing key (hidden prompt)	`.venv/Scripts/python.exe -m scripts.wallet import --chain evm`

Wallets can also be created and checked from the bot's Wallets menu.

Fund the addresses on the network you want to trade:

To trade on	Send	To
Robinhood Chain, Ethereum, Arbitrum, Base	ETH on that network	your `0x…` address
BNB Chain	BNB	your `0x…` address
Solana	SOL	your Solana address

Caution

When withdrawing from an exchange, pick the matching network. The address looks valid on every EVM chain, so a wrong network is the easiest way to lose funds.

Keep gas on top of the trade size. Solana buys require trade size + 0.01 SOL (fees, Jito tip and token-account rent); Robinhood Chain v4 swaps use about 1M gas.

Then start the bot again:

pm2 start ecosystem.config.js --only mcb

8. First run

Step 1 — Start

pm2 start ecosystem.config.js

pm2 status

mcb should be online.

Step 2 — Open your bot in Telegram and send /start. The main menu shows the mode (DRY RUN or live), open positions and how many chats are watched.

Step 3 — Pick signal sources. Tap Groups or Channels and switch on the chats to buy from (see section 10).

Step 4 — Set your rules. Open Settings (buy size, TP/SL), Filters (chains, token age) and Safety (taxes, liquidity).

Step 5 — Turn Auto-buy ON in the main menu.

Step 6 — Watch it

pm2 logs mcb

Every signal is logged with the reason it was bought or skipped. Buy, sell and error notifications also arrive in your bot chat.

9. Using the bot in Telegram

9.1 Main menu

Button	What it does
Auto-buy: ON/OFF	Master switch. OFF still reads and logs signals, but never buys.
Dashboard	Opens the portfolio inside Telegram (appears once a tunnel is running).
Positions (N)	Open positions with live P&L; sell 25/50/100%; per-token TP/SL/trail/time overrides.
Settings	Buy size per chain, slippage, Solana priority fee, Jito tip, EVM priority fee, TP tiers, moonbag, stop loss, trailing stop and arming, time exit, max positions.
Groups / Channels	Choose which chats the bot buys from.
Wallets	Create or view a wallet per chain and read live balances.
Safety	Honeypot check, anti-rug check, require locked LP, max buy/sell tax, minimum liquidity.
Filters	Enabled chains, blacklist words, sender whitelist, token blacklist, cooldown, min/max token age, skip tokens traded before.

Tap any setting, send the new value, and it is saved immediately. /cancel aborts an edit.

9.2 Commands

Command	Description
`/start`, `/menu`	Open the main menu.
`/groups`	Groups screen.
`/channels`	Channels screen.
`/addchannel <link or @name>`	Join a channel and add it (OFF). `/addgroup` does the same for groups.
`/buy <address>`	Manual buy with your default size (no age limit).
paste an address	Offers a one-tap manual buy.
`/wallets`	Wallets screen.
`/export <chain>`	Show a private key; the message self-destructs after 60 seconds.
`/dashboard`	Dashboard button, or instructions to enable it.
`/panic`	Emergency: auto-buy OFF and sell every open position.

9.3 Notifications

Signal — every detected address, and whether it was queued or filtered.
BUY / SELL — size, tokens, transaction link, safety caveats, P&L.
Error — failed quotes, simulations, insufficient balance, dropped transactions, each with the reason.

10. Signal sources: groups and channels

The bot can read any chat your own account has joined.

Groups are chats where members post (including supergroups). Channels are broadcast channels where only admins post. Both screens work the same way:

Signal Channels

Tap a channel to switch buying on or off.

Watching: 1 of 23 channels

Active
  ON  Alpha Calls  (12 signals)

Page 1 of 3

[ON] Alpha Calls
[  ] Solana Gems VIP
...
[< Prev] [Next >]
[Groups] [Refresh] [Back]

Tap a chat to switch it ON / OFF. It takes effect on the next message, with no restart.
Refresh re-reads your Telegram chats (new joins appear OFF).
10 chats per page.

Add a channel you have not joined yet:

/addchannel @channelname
/addchannel https://t.me/channelname
/addchannel https://t.me/+InviteCode

Your account joins it and it is added OFF with a Turn buying ON button. Private invites that need admin approval report that instead.

Reliability for channels: Telegram can delay live updates from large channels, so every 15 seconds the bot also re-reads the newest posts of each enabled channel (up to 25). A post received both ways is processed once.

11. What gets bought: the filter pipeline

A message must pass every step, in this order:

#	Check	Skipped when
1	Token address present	No EVM or Solana address in the text. Silent.
2	Chat enabled	The group/channel is OFF.
3	Fresh post	Posted before the chat was switched on, or more than 5 minutes ago.
4	Not already processed	The same message was already handled (edit, or seen by the channel poller).
5	Auto-buy	Auto-buy is OFF.
6	Enabled chains	The token's chain is not in your list (empty list = all chains).
7	Blacklist words / sender whitelist / token blacklist	A match (or sender not on a non-empty whitelist).
8	Per-token rule	You disabled that token.
9	Position checks	Already holding it, or Max positions reached.
10	Cooldown	Same token called within the cooldown window.
11	Balance	Wallet holds less than trade size (+0.01 SOL reserve on Solana).
12	Token age	First pool is younger than Min or older than Max token age (default 2–8 days).
13	Traded before	You held this token before and Skip tokens traded before is ON.
14	Round-trip quote	EVM chains without honeypot coverage: buy-then-sell quote loses more than buy tax + sell tax + 5%.
15	Safety checks	See section 13.
16	Pre-send simulation	The exact transaction would fail on-chain. Nothing is sent.

Manual buys (/buy or a pasted address) skip steps 2–10 and 12–13.

Skipped signals are logged with the reason (signal.not_queued, buy.rejected_*) and kept in data/signals.json.

12. Exit strategy

Evaluated on every price update, plus a sweep every 10 seconds so a stalled price feed still triggers stops. First match wins:

Priority	Rule	Behaviour
1	Stop loss	Price ≤ entry × (1 − SL%) → sell 100%.
2	Trailing stop	Armed once up Trail arms % (default +30%); sells when price falls Trail % (default 20%) below the peak.
3	Take profit	Sells the size of the highest unfilled tier the price has reached. Sizes are % of the original position.
4	Time exit	Sells after Time exit minutes (0 = off).
—	Moonbag	A % of the original position that take-profit never sells. Only stop, trail, time exit or a manual sell closes it.

Example: "recover my cost at 2x, ride the rest"

Setting	Value
TP tiers	`100:50`
Moonbag	`50`
Stop loss	`35`
Trail / arms	`20` / `30`

At +100% the bot sells half, which returns your full stake. The other half is free and rides until the trailing stop or stop loss closes it.

Per-token overrides

Open Positions → token to change TP, SL, trail or time exit for that position only. Global settings changed later never rewrite open positions.

13. Safety checks

Check	Chains	Blocks the buy when
Honeypot simulation (honeypot.is)	Ethereum, BNB, Arbitrum, Base	The token cannot be sold (Honeypot check ON), or the simulated buy/sell tax exceeds your limits.
Contract scan (GoPlus, Anti-rug check)	All EVM incl. Robinhood	Ownership reclaimable, hidden owner, self-destruct, pausable transfers, blacklist function, or per-wallet slippage control. Mintable supply and upgradeable proxies are reported as warnings.
Anti-rug (RugCheck, Anti-rug check)	Solana	Mint or freeze authority still enabled, single-holder ownership, large unlocked LP, any "danger" flag, or a risk score of 60+.
Liquidity floor	All	Pool liquidity below Min liquidity (default $5,000).
LP locked	All (optional)	Require LP locked is ON and liquidity is not locked.
Round-trip quote	Robinhood Chain	Buy-then-sell loses more than your tax limits + 5%.
Pre-send simulation	All	The exact transaction would revert or fail.

If honeypot.is (EVM) or RugCheck (Solana) is unreachable while a check is ON, the trade is skipped, never sent blind. Liquidity is the deepest pool reported by DexScreener. Buys on Robinhood Chain carry an UNVERIFIED: no honeypot simulation caveat because honeypot.is does not cover it.

14. Dashboard (PC and phone)

On this PC: open http://localhost:8080/. It shows portfolio value, wallet balances, open and closed positions and per-token P&L, refreshing every few seconds.

Inside Telegram on your phone (free):

Download cloudflared-windows-amd64.exe from https://github.com/cloudflare/cloudflared/releases/latest.
Save it as tools\cloudflared.exe inside the project folder.

Start the tunnel:

pm2 start ecosystem.config.js --only tunnel

pm2 save

After about 20 seconds, send /dashboard to your bot (or reopen the menu) and tap Dashboard.

The quick-tunnel address changes whenever the tunnel restarts; the bot detects the new one automatically, so just send /dashboard again. Access is limited to the Telegram IDs in TELEGRAM_ADMIN_IDS (Telegram signs every request); anyone else gets 401.

15. Running 24/7 with PM2

Task	Command
Start everything	`pm2 start ecosystem.config.js`
Status	`pm2 status`
Live logs	`pm2 logs mcb`
Last errors	`pm2 logs mcb --err --lines 50`
Restart after editing `.env`	`pm2 restart mcb --update-env`
Stop	`pm2 stop mcb`
Resource monitor	`pm2 monit`

Start on boot (Windows):

npm install -g @jessety/pm2-installer

pm2-installer install

pm2 save

On Linux use pm2 startup (run the command it prints), then pm2 save.

Tip

In an emergency send /panic in Telegram rather than pm2 stop. Stopping the process leaves positions open with no stop loss watching them.

16. Going live

Only after dry run has shown a full buy → take-profit → stop-loss cycle:

Create a fresh wallet (scripts.wallet create) and fund it with a small amount.
Set DRY_RUN=false in .env.
Restart:
```
pm2 restart mcb --update-env
```
Do one manual buy and a Sell 100% from Positions to prove the full path on your key.
Turn Auto-buy ON.

Start with one signal source and a buy size you would not mind losing. Step-by-step for Robinhood Chain: ROBINHOOD_TEST.md.

17. Robinhood Chain

Robinhood Chain is a public Arbitrum Orbit L2 (chain ID 4663, ETH for gas) and home of tokenized stocks. It is a normal EVM chain here, unrelated to the Robinhood brokerage app.


Chain ID	4663
RPC	Alchemy `robinhood-mainnet`, fallback `https://rpc.mainnet.chain.robinhood.com`
Explorer	https://robinhoodchain.blockscout.com
WETH	`0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73`
USDG	`0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`
DexScreener slug	`robinhood`

Routing. Every quote compares:

Uniswap v3 — QuoterV2 across fee tiers, SwapRouter02; sells unwrap to native ETH.
Uniswap v4 — routes of up to three hops (ETH→token, ETH→X→token, ETH→USDG→X→token) through pools with at least $1,000 liquidity, executed via the Universal Router. Sells approve Permit2 once per token. Pool keys are cached in data/v4_pool_keys.json.

v4 pools can have hooks that take fees or alter output, so hooked routes are guarded by the round-trip quote, the hook flags shown in the buy notification, and the pre-send simulation.

18. Data, backups and security

Files in `data/`

File	Contents
`users.json`	Telegram user, auto-buy flag
`user_settings.json`	All settings from the Telegram menus
`wallets.json`	Addresses and encrypted private keys
`sources.json`	Groups and channels, ON/OFF, when enabled
`positions.json`	Open and closed positions with their exit plans
`orders.json`	Every buy and sell with its transaction hash and status
`token_rules.json`	Per-token overrides
`signals.json`	Signal audit log (newest 2,000 kept)
`v4_pool_keys.json`	Uniswap v4 pool cache

Writes are atomic (.tmp then rename), the previous version is kept as .bak and loaded automatically if a file is ever unreadable, and a .lock file stops two copies from running.

Backups

Back up data/ and MASTER_ENCRYPTION_KEY together, offline. Either one alone is useless.

Security checklist

TELEGRAM_ADMIN_IDS is set (empty means anyone can use the bot).
The wallet is a dedicated burner, not your main wallet.
.env, data/ and saved key files are not in cloud sync or git.
Private keys are never pasted into Telegram or chat tools.
USE_PRIVATE_RPC=true and JITO_TIP_LAMPORTS > 0.

Logs redact key material and strip API keys from RPC URLs in error messages.

19. Troubleshooting

Symptom / message	Cause and fix
Bot does not answer `/start`	Your ID is not in `TELEGRAM_ADMIN_IDS`, or you restarted without `--update-env`.
`mcb` keeps restarting	`pm2 logs mcb --err --lines 50`; run `scripts.doctor`.
`another instance is already using data`	A copy is still running. `pm2 stop mcb`; if none is running, delete `data/.lock`.
Chat missing from Groups/Channels	Join it with your account (or `/addchannel`), then tap Refresh.
`signal.ignored_old_message`	Posted before the chat was switched on, or over 5 minutes old. Expected.
`auto-buy is OFF`	Turn Auto-buy ON.
`too new` / `too old`	Outside your Min/Max token age window. Adjust in Filters.
`already traded this token before`	Skip tokens traded before is ON.
`insufficient SOL/ETH`	Fund the wallet; Solana needs trade size + 0.01 SOL.
`round trip loses …%`	Likely honeypot or heavy hook fee. Not bought, by design.
`pre-send simulation failed/reverted`	The transaction would have failed; nothing was sent or spent.
`no Uniswap route with liquidity`	No v3 pool or v4 route with enough liquidity.
`transaction too large`	No Solana route small enough to fit a transaction; nothing was sent.
`never landed … nothing was spent`	A transaction was dropped by the network; the position is corrected automatically.
Dashboard button missing	Tunnel not running: `pm2 start ecosystem.config.js --only tunnel`, wait 20 s, `/dashboard`.
Bot is in DRY RUN unexpectedly	Check `DRY_RUN` in `.env`, then `pm2 restart mcb --update-env`.

20. Project structure

multi-chain-bot/
├── app/
│   ├── main.py                 Entry point: starts every component in one process
│   ├── config.py               Settings from .env, chain constants, RPC resolution
│   ├── signals/
│   │   ├── parser.py           Address extraction, chain detection, filters
│   │   └── listener.py         Telethon userbot, freshness, channel poller, fan-out
│   ├── chains/
│   │   ├── solana.py           Jupiter, Jito, simulation, size guard
│   │   ├── evm.py              1inch / routers, Uniswap v3, approvals, relays
│   │   ├── uniswap_v4.py       v4 routing, PoolKey recovery, Universal Router
│   │   ├── router.py           Chain → adapter
│   │   └── alchemy.py          Notify webhooks
│   ├── engine/
│   │   ├── executor.py         Buy/sell execution and bookkeeping
│   │   ├── position_manager.py Exit-rule evaluation
│   │   └── worker.py           Worker pool and transaction reconciler
│   ├── pricing/
│   │   ├── feed.py             DexScreener / Birdeye prices
│   │   └── safety.py           honeypot.is, GoPlus, RugCheck, liquidity
│   ├── bot/                    aiogram UI: menus, handlers, views
│   ├── api/                    Dashboard, Telegram Mini App auth, tunnel, webhooks
│   ├── store/                  Atomic JSON store and data models
│   └── db/                     Repository layer and settings migrations
├── scripts/
│   ├── doctor.py               Pre-flight diagnostics
│   ├── wallet.py               create / list / export / import
│   ├── gen_master_key.py       Generate MASTER_ENCRYPTION_KEY
│   ├── gen_session.py          Log in your Telegram account (StringSession)
│   ├── init_db.py              Create data files
│   └── list_chats.py           Print chat IDs
├── tests/                      pytest suite
├── tools/                      cloudflared.exe (you add it)
├── data/                       Runtime state (created on first run)
├── ecosystem.config.js         PM2 processes: mcb (+ tunnel)
├── requirements.txt
└── .env.example

21. Development and tests

.venv/Scripts/python.exe -m pytest -q

202 tests cover the signal parser and filters, message freshness, channel link parsing and polling, exit rules (tiers, moonbag, trailing arming), the encrypted keystore, JSON persistence and settings migration, the full signal → buy → exit flow against the real store, sell/reconcile corrections, Solana simulation and transaction-size handling, Uniswap v4 calldata and routing, dashboard auth and tunnel detection, and log redaction.

Chain adapters talk to live networks; exercise them with DRY_RUN=true (see TESTING.md).

22. Documentation index

Document	Use it for
SETUP.md	Detailed installation on Windows with PM2, funding, reboot survival.
USAGE.md	Day-to-day guide: sources, rules, the 2x moonbag setup, phone dashboard.
TESTING.md	Rehearse the whole flow with no money in dry run.
ROBINHOOD_TEST.md	Exact steps for the first real trade on Robinhood Chain.

Disclaimer

This software is provided as-is, for personal use, without warranty of any kind. It is not financial advice. Trading newly launched tokens carries a high risk of total loss, including through scams that no automated check can detect. You are solely responsible for your keys, your funds and your compliance with local laws.

Educational Purpose Notice

This bot is built solely for educational purposes — to learn and understand Web3 development, blockchain layers (L1, L2, Orbit chains), smart contract interaction, MEV protection, transaction simulation, and multi-chain trading logic. It is a personal research project with no commercial motive, no affiliation with any protocol or exchange, and no intention of being offered as a service or product.

Use it only to study the code, architecture, and on-chain mechanics. Any live trading is done entirely at your own risk and discretion. The author assumes no liability for any financial losses, technical failures, or regulatory issues arising from its use.

Name		Name	Last commit message	Last commit date
app		app
logs		logs
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
ROBINHOOD_TEST.md		ROBINHOOD_TEST.md
SETUP.md		SETUP.md
TESTING.md		TESTING.md
USAGE.md		USAGE.md
ecosystem.config.js		ecosystem.config.js
pytest.ini		pytest.ini
requirements.txt		requirements.txt
skills-lock.json		skills-lock.json

Latest commit

History

Folders and files

Repository files navigation