Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/backtest-kit/ai-trading-mcp/llms.txt

Use this file to discover all available pages before exploring further.

AI Trading MCP scrapes a Telegram channel and pipes its posts — including chart screenshots — into the get_status MCP feed. That requires a user session, not a bot token: the GramJS client logs in as your real Telegram account and reads exactly the channels you can read. Bots cannot access arbitrary channels they have not been invited to, and the Telegram Bot API has no equivalent to fetching message history with photo attachments. The trade-off is that the session grants broad account access, which is why the security steps below matter.

​
Why a User Session

Full channel access

A user session reads any channel you are a member of — public, private, or invite-only — including full message history and photo attachments, exactly as they appear in the Telegram app.

Image blocks in get_status

Chart screenshots from the feed arrive as MCP image blocks because GramJS can download Telegram media directly. The scraper picks the smallest photo size with width ≥ 800 px to keep payloads lean.

No bot invite required

You do not need to add a bot to the channel or get admin approval. If your account can read it, the scraper can read it.

Session survives restarts

The session string is saved to session.txt and loaded at startup. The trading process reconnects automatically without re-scanning the QR code.

​
Authorization Steps

1

Get API credentials from my.telegram.org

Open https://my.telegram.org and log in with your Telegram account.Navigate to API Development Tools and create an application if you have not already. Copy the App api_id (a number) and App api_hash (a hex string) — you will need both in the next step.
Do not use the fallback credentials shipped in the source (CC_TELEGRAM_API_ID = 31861455, CC_TELEGRAM_API_HASH = "ca60446c67ce250ee4e789c730163449"). They are shared dev values. Sessions authorized with them are accessible to anyone holding the same pair, and Telegram throttles API calls across all users of a given api_id. Always register your own application.
2

Set credentials in your environment

Export the values before running the auth command, or add them to your .env:
export CC_TELEGRAM_API_ID=12345678
export CC_TELEGRAM_API_HASH=your_api_hash_here
Or in .env:
CC_TELEGRAM_API_ID=12345678
CC_TELEGRAM_API_HASH=your_api_hash_here
3

Run the session command

From the packages/main directory, run the session authorizer:
# With environment variables already set
npm start -- --session

# Or use the convenience script (loads .env automatically)
npm run auth
Both commands invoke the same session.ts entrypoint — npm run auth just ensures .env is sourced before the process starts.
4

Scan the QR code

A QR code renders directly in the terminal. On your phone, open Telegram and navigate to:Settings → Devices → Link Desktop DevicePoint the camera at the terminal QR code. Telegram will confirm the link on your phone.
5

Enter your 2FA password (if prompted)

If your Telegram account has Two-Step Verification enabled, the terminal will prompt:
Enter your 2FA password:
Type your cloud password and press Enter. The prompt is handled via readline and never echoed to the shell history.
6

Confirm session.txt is written

On success the process prints:
Connected!
Session saved to ./session.txt
The session string is written to session.txt in the current working directory — wherever you ran the command. At runtime, the trading process reads it from the strategy’s working folder:
content/manual.strategy/session.txt
If you ran the auth command from packages/main, move or copy the file to that path:
mv ./session.txt ../../content/manual.strategy/session.txt

​
How the QR Auth Flow Works

The session command runs client.signInUserWithQrCode() from GramJS. The qrCode callback converts the login token to a tg:// deep-link URL and renders it as a QR code in the terminal using qrcode-terminal. The password callback pauses for 2FA input over readline before the session string is saved: 
await client.signInUserWithQrCode(
  { apiId: CC_TELEGRAM_API_ID, apiHash: CC_TELEGRAM_API_HASH },
  {
    qrCode: async ({ token }) => {
      const url = `tg://login?token=${token.toString("base64url")}`;
      console.clear();
      console.log(
        "Scan this QR code in Telegram app (Settings -> Devices -> Link Desktop Device):\n"
      );
      qrcodeTerminal.generate(url, { small: true });
    },
    password: async () =>
      new Promise((resolve) =>
        rl.question("Enter your 2FA password: ", resolve)
      ),
    onError: async (err) => {
      console.error(err.message);
      return false;
    },
  }
);

​
How the Session Is Loaded at Runtime

The trading process uses getTelegram() from packages/agent/src/config/telegram.ts to connect. The function is wrapped in singleshot() from functools-kit, which memoizes the result — the first call reads session.txt, creates the TelegramClient, and connects; every subsequent call returns the same client instance without re-reading the file: 
export const getTelegram = singleshot(async () => {
  const session = await readFile("./session.txt", "utf-8");
  const stringSession = new StringSession(session);
  const client = new TelegramClient(
    stringSession,
    CC_TELEGRAM_API_ID,
    CC_TELEGRAM_API_HASH,
    {
      connectionRetries: 5,
      systemVersion: "Windows 10",
      deviceModel: "Desktop",
      appVersion: "1.0.0",
    }
  );
  await client.connect();
  await client.getMe();
  return client;
});
The singleshot() wrapper is cleared on a Telegram timeout — when the 90-second feed fetch times out, StatusControllerService calls telegram.disconnect() followed by getTelegram.clear(), so the next getTelegram() call re-reads session.txt, creates a fresh TelegramClient, and reconnects. This means the client self-heals after transient disconnects without restarting the process.
If session.txt is missing or unreadable, the catch block in getTelegram logs: "No session found. Please run 'npm start -- --auth' to create a session." The flag --auth in this error message is a bug in the source — the actual CLI flag parsed by getArgs.ts is --session. Use npm start -- --session or the npm run auth convenience script (which runs dotenv -e .env -- npm start -- --session) to create the session file.

​
Securing session.txt

session.txt contains a serialized GramJS StringSession that grants full access to the Telegram account that scanned the QR code — read access to all channels, send access to all chats. Treat it with the same care as an SSH private key or an OAuth refresh token.

Keep it out of version control

The repository’s .gitignore already excludes session.txt. Verify that the exclusion is in place before your first commit, especially if you initialize a new repo from this template.

Restrict file permissions

On Linux/macOS, set restrictive permissions so only the process owner can read the file:
chmod 600 content/manual.strategy/session.txt

Don't run on shared machines

Anyone with read access to the filesystem — including other users on the same host — can extract the session string and use it to access your Telegram account. Run the trading process on a machine you control exclusively.

Revoke if compromised

If session.txt is ever exposed, revoke the session immediately from Telegram: Settings → Devices → find the authorized device → Terminate Session.

Build docs developers (and LLMs) love

Get started for freeTalk to us