メインコンテンツへ移動
AIチュートリアル

Node.jsとTelethonセッションでATF Telegramミニアプリを自動化

このチュートリアルでは、ATF Bot Automation v2のインストール、Telegram認証情報の設定、Telethonセッションの読み込み、TONウォレットの作成と検証、対話型または無人ワークフローの実行方法を説明します。タスクワーカー、紹介登録、Turnstileソルバー、プロキシ、ダッシュボード、出金、リトライ、重要なシークレット管理上の注意点についても解説します。

約24分で読了
Node.jsとTelethonセッションでATF Telegramミニアプリを自動化

ATF Bot Automation v2 の機能

ATF Bot Automation v2 は、アクティブな Telethon SQLite セッションファイルを使用して ATF Telegram Mini App とやり取りする Node.js ボットです。静的なクエリファイルに Telegram.WebApp.initData を保存する代わりに、サイクルごとに新しい Telegram WebView をリクエストし、Telegram から返される最新の初期化データを使用します。

このボットは複数のアカウントに対応しており、ATF ログイン、TON ウォレットの作成と検証、マイニング報酬の請求、動的タスク、紹介登録、アカウント統計、ウォレット交換、ATF 出金を管理できます。サイクルごとにセッションディレクトリを再スキャンするため、ソースコードを変更せずに新しく追加されたアカウントを検出できます。

主な機能

  • サイクルごとに最新の Telegram WebView と Mini App 初期化データを取得。
  • Telethon SQLite セッションデータベースへの読み取り専用アクセス。認証キーは一時的にメモリへコピー。
  • 実際の TON v4r2 メインネットウォレットアドレスを自動作成。
  • ATF の sync_wallet エンドポイントを通じた TON Proof 署名とウォレット検証。
  • 一時的な busy 応答や、キャッシュ・重複排除された応答を受け取るアカウント向けのキュー式ウォレットワーカー。
  • eval を使用せず、Acorn で ATF フロントエンド設定を解析して動的にタスクを検出。
  • セッションごとに独立したタスクワーカーとオンボーディング状態。
  • Telegram messages.StartBot による紹介登録（Turnstile 対応を含む）。
  • ATF リクエストごとにアカウント別の HTTP または HTTPS プロキシ設定。
  • 自動化をリアルタイムで確認できる Textual ダッシュボードと、別の読み取り専用統計ダッシュボード。
  • 残高確認、画像 CAPTCHA 解決、プロキシローテーション、出金履歴レポートに対応した順次出金。
  • 安定したリクエスト ID、制御されたリトライ、正常なシャットダウン、ログ内の機密値フィルタリング。

必要条件

プロジェクトをインストールする前に、以下を準備してください。

  • Node.js 22.5 以降。
  • https://my.telegram.org/apps から取得した、ご自身の Telegram API ID と API ハッシュ。
  • .session で終わる、アクティブな Telethon SQLite セッションファイルを少なくとも 1 つ。
  • Textual ダッシュボードまたはローカル Turnstile ソルバーを使用する場合は Python 3。
セキュリティ警告: Telegram API ハッシュ、Telethon セッションファイル、プロキシ認証情報、.env、wallets-accounts.json は絶対に共有しないでください。ウォレットファイルには平文のニーモニックと秘密鍵が含まれており、保存されているすべてのウォレットを完全に制御できます。

ボットのインストールと設定

1. Node.js の依存関係をインストールする

プロジェクトのルートで PowerShell を開き、パッケージをインストールします。

npm install
Copy-Item .env.example .env

2. Telegram API 認証情報を追加する

.env を編集し、Telegram アプリケーション用に発行された認証情報を入力します。

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_api_hash

これらの認証情報はご自身のものでなければなりません。入力済みの環境ファイルをバージョン管理にコミットしないでください。

3. Telethon セッションを追加する

アクティブな SQLite セッションファイルをすべて session ディレクトリに配置します。ファイル名がボットに表示されるアカウントラベルになります。

session/
├── account1.session
├── account2.session
└── account3.session

このディレクトリは各サイクルでスキャンされます。セッションデータベースは読み取り専用で開かれ、同一アカウントのセッションへのアクセスはキューに入れられるため、同時操作の衝突を防げます。

4. Textual ダッシュボードを任意でインストールする

メインの自動化機能では、ネイビー、バイオレット、コーラルを基調とした Textual ダッシュボードを表示できます。Python の依存関係を一度インストールしてください。

python -m pip install -r requirements-textual.txt

Python が標準とは異なる場所にインストールされている場合は、ATF_PYTHON に python.exe の完全なパスを設定してください。

ボットを実行する

次のコマンドで対話型メニューを起動します。

npm start

メニューでは以下のワークフローを利用できます。

[1] Run BOT
[2] Register accounts with referral code
[3] Replace TON wallet
[4] Check account statistics
[5] Withdraw ATF
[0] Exit

メインの自動化を実行する

オプション 1 を選択すると、Textual ダッシュボード付きで Node.js ワーカーが起動します。ダッシュボードには、Telegram ユーザー名、レベル、採掘済み ATF、ATF 保有量、保留中の報酬、ウォレット状態、マイニング状態、タスク請求状況、タスクのカウントダウン、紹介結果、Team Wallet の詳細、接続状況、サイクル概要が表示されます。

便利なダッシュボード操作:

  • q: 正常に停止して終了。
  • p: ワーカーを一時停止または再開。
  • r: すべてのアカウントの統計を並列で更新。
  • c: ログパネルをクリア。
  • PgUp と PgDn: ログをスクロール。
  • g と Shift+G: ログの先頭または末尾へ移動。

ダッシュボードは、デフォルト値が 10 分の dashboard_refresh_interval_minutes に従ってアカウント状態を自動更新します。直接起動するには、次を使用します。

npm run dashboard

Textual を使わず標準的なターミナルログを表示するには、次を実行します。

npm run start:run

このコマンドは、スケジューラーや非対話型プロセスのエントリーポイントとしても適しています。

TON ウォレット設定の仕組み

アカウントのログイン後、ボットは ATF サーバーの wallet_address と wallet_verified フィールドを確認します。検証済みウォレットが存在しない場合は、次の手順に従います。

  1. メインネット用のTON v4r2ウォレットを作成します。
  2. そのアドレス、24語のニーモニック、秘密鍵を直ちにwallets-accounts.jsonへ保存します。
  3. ATFから公式TON Proofペイロードを要求します。
  4. ATF WebAppドメイン用のProofに署名します。
  5. Proofをsync_walletへ送信します。
  6. 検証が成功した後にのみ、セキュリティ質問とマイニングへ進みます。

ウォレットのレコードは検証開始前に書き込まれます。そのため、一時的なbusy応答やアカウントの処理延期によって、新しく生成されたウォレットが失われることはありません。

ウォレットが未検証のままATFがbusyまたはキャッシュ済み・重複排除済みの応答を返した場合、メインプロセスはwallet_busy_retry_seconds（デフォルトは15秒）の経過後に1回再試行します。アカウントが引き続きビジーの場合はウォレットワーカーへ移され、メインプロセスは処理を続行できます。

wallet_worker_concurrencyで指定した数のウォレットジョブが並列で実行されます。デフォルトは10です。追加のアカウントはFIFOキューに入ります。各セッションにつき、アクティブまたはキュー待ちのウォレットワーカーは1つだけ許可されます。

生成されたウォレットは実在するウォレットアドレスですが、オンチェーントランザクションで使用されるまでオンチェーンにはデプロイされません。wallets-accounts.jsonを安全に保管し、慎重にバックアップしてください。このファイルを持つ人は誰でもウォレットを操作できます。

encrypted_secretsを含む古いレコードは、ボットが初めて開く際に平文形式へ移行されます。以前のWALLET_KEYSTORE_PASSWORDが必要なのは、この移行時だけです。

紹介登録を設定する

オプション2で新しいアカウントを登録する場合は、config.jsonに紹介コードを追加します。

{
  "referral_code": "610911604"
}

そのコードでまだ処理されていない各セッションについて、ボットはTelegramのmessages.StartBotを呼び出し、同じ開始パラメータでWebViewを開き、ATFログイン時にref_codeを送信します。成功した結果は.state/referrals.jsonにハッシュとして記録され、同じStartBot操作が毎サイクル繰り返されるのを防ぎます。

紹介モードが処理するのは紹介登録だけです。ウォレットの作成と保存は、オプション1によるメイン自動化の一部として引き続き行われます。既存のアカウントでは、サーバーにすでに記録された招待者を通常は変更できません。

対話型メニューを使わずに紹介登録を直接実行するには、次のコマンドを実行します。

npm run register-referral

TurnstileにMultiBotを使用する

新しいアカウントでCloudflare Turnstileチャレンジが表示された場合、ボットはATFから公式のsite_keyを取得し、MultiBotにトークンを要求できます。APIキーを.envに追加します。

MULTIBOT_API_KEY=your_api_key

デフォルトでは、アカウントのプロキシはMultiBotへ送信されません。同じプロキシIPを使って解決する必要がある場合は、次を有効にします。

MULTIBOT_USE_ACCOUNT_PROXY=1
この設定を有効にすると、アカウントのプロキシアドレスと認証情報がMultiBotへ送信されます。このオプションを使用する前に、その情報が公開されることを検討してください。

ローカルTurnstileソルバーを実行する

付属のローカルソルバーは127.0.0.1:8000にのみバインドします。Windowsでは、Python 3をインストールし、プロジェクトルートからソルバーを準備します。

py -3 -m venv local-solver\.venv
local-solver\.venv\Scripts\python.exe -m pip install -r local-solver\requirements.txt
local-solver\.venv\Scripts\python.exe -m camoufox fetch
cd local-solver
.venv\Scripts\python.exe api_server.py --yes

そのターミナルは開いたままにします。別のターミナルでボットを実行し、オプション2を選択して、ローカルソルバーを選びます。非対話型で実行する場合は、次のように設定します。

TURNSTILE_SOLVER=local
LOCAL_TURNSTILE_SOLVER_URL=http://127.0.0.1:8000

アカウントごとの上書きを適用する

個々のセッションで異なる設定が必要な場合は、account-overrides.example.jsonをaccount-overrides.jsonへコピーします。例：

{
  "account1.session": {
    "enabled": true,
    "proxy": "http://username:password@127.0.0.1:8080",
    "ready_task_ids": ["telegram_join"]
  }
}
  • enabledはセッションを有効化または無効化します。
  • proxyはATFリクエスト用のHTTPまたはHTTPSプロキシを設定します。Telegram MTProtoは直接接続のままです。
  • ready_task_idsは、手動で実際に完了した1回限りのタスクを示します。これらのタスクはボットが取得できるようになります。

上書きファイル、プロキシ、環境ファイル、キャッシュ、状態ファイル、セッションファイルはGitの対象外です。

動的タスクを設定する

ATFはタスクリストのエンドポイントを公開していません。その代わり、フロントエンドはindex.html内のインラインJavaScriptとしてtasksConfigを含んでいます。ボットはそのページをダウンロードし、コードを実行せずにAcornで抽象構文木を解析します。抽出するのは、タスクID、タイトル、報酬、リンク、クールダウン、最短所要時間、手動確認が必要かどうかだけです。

ページを読み込めない場合、ボットは最新のキャッシュを使用します。フロントエンドもキャッシュも利用できない場合は、ハードコードされたフォールバックを使わず、そのサイクルのタスク取得を無効にします。

config.jsonでタスクモードを次のいずれかに設定します。

  • off：タスクを読み込まず、処理もしません。
  • report：利用可能なタスクを表示しますが、開始も取得もしません。
  • claim_ready：start_taskでリンククリックを登録し、対象となるタスクを開始し、各minSeconds期間を並列で待機して、準備ができたタスクを取得します。

ready_task_ids に記載されたタスクは、再度開始されることなく取得キューに入ります。初回ログインを順番に行った後、各アカウントに個別のタスクワーカーが割り当てられます。ワーカーはそのアカウントのクールダウンが終了するまで待機し、サーバーの状態を再読み込みして準備済みタスクを処理し、最新のレスポンスを基に次回実行をスケジュールします。

準備済みタスクを開始または取得できない場合、リトライは task_ready_retry_seconds によって制限され、デフォルトは 60 秒です。これにより、短い間隔でのリトライループを防ぎます。loop_interval_hours 設定はマイニング取得サイクルにのみ適用され、タスクのスケジューリングには適用されません。

TONウォレットを安全に交換する

オプション 3 を選択するか、対話型ターミナルで npm run replace-wallets を実行すると、交換が必要な可能性のあるウォレットについてセッションをスキャンします。wallets-accounts.json に有効なニーモニックと秘密鍵がすでに保存されているアカウントはスキップされます。

ローカルにシークレットがない検証済みウォレットについて、ボットは、そのウォレットがバックアップを失った古いボットインストールに由来するのか、外部ウォレットに由来するのかを判定できません。そのため、ユーザー名とマスクされたアドレスを表示し、アカウントごとに確認を求めます。

  • y を入力するとウォレットを交換します。
  • Enter または n を押すとスキップします。
  • q を入力すると残りのスキャンをキャンセルします。

承認後、新しいウォレットとニーモニックが保存され、その後 sync_wallet と TON Proof を通じて ATF がアトミックに更新されます。以前のウォレットにあるオンチェーン資産は移転されません。処理中の交換は replacement_pending として保存され、スキャン後に最大 5 つのワーカーによって再試行されます。中断された交換は、再度オプション 3 を実行することで再開できます。

アカウント統計を監査する

オプション 4 または npm run stats で、読み取り専用の監査ダッシュボードを開きます。最新のログインを実行し、sync_wallet を呼び出して、get_withdraw_history を読み取ります。同時実行数は stats_worker_concurrency で制御され、最大 5 ワーカーに制限されます。

ダッシュボードには、ユーザー名、ウォレットアドレス、ATF保有量、マイニング残高、BAN状態、リスクスコア、条件を満たしたDEX購入状況、保留中の出金、最新の出金ステータス、および masked_auto_fraud の FRAUD MASK が表示されます。出金状態には NONE、PENDING、APPROVED、KYC/VERIFY、FAILED、UNAVAILABLE が含まれます。KYCステータスと不正マスクは別々のシグナルです。

r を押すと監査を再実行し、q を押すと終了します。

ATFを出金する

オプション 5 はアカウントを順番に処理し、出金リクエストごとにサーバーが 70 ATF を請求するため、開始前に 1 回の確認を求めます。

各アカウントについて、ボットは次の処理を行います。

  1. 新しいセッションでログインし、mined_balance と pending_reward を読み取ります。
  2. 保留中の報酬を取得します。
  3. 再度ログインしてマイニング残高を更新します。
  4. 残高が 500 ATF 未満、またはウォレットが未検証の場合はアカウントをスキップします。
  5. 出金可能なマイニング残高全額を小数点以下 4 桁に切り捨てます。
  6. 画像CAPTCHAを解いて出金を送信します。
  7. 出金履歴を読み取り、最終的に利用可能なステータスを報告します。

ImageToTextTask ソルバー用に、.env に 2Captcha キーを追加します。

TWOCAPTCHA_API_KEY=your_api_key

ボットは送信前に、フロントエンド公式の 1.2～2 秒のジッターを適用します。CAPTCHAの回答が失敗または拒否された場合は、新しいチャレンジを要求します。試行回数は withdraw_captcha_max_attempts（上限 3）とサーバーの attempts_left のうち、少ない方までです。

retry_after_seconds レスポンス、出金ロック、またはサーバー試行回数の枯渇が発生すると、そのアカウントのリトライを停止します。次のコマンドで出金を直接実行できます。

npm run withdraw

出金にプロキシを使用する

proxy.txt または proxies.txt にプロキシが含まれている場合、出金モードはバッチ全体用に一意のプールを作成します。各プロキシは失敗した場合でも 1 回しか選択されず、そのバッチ中に別のアカウントへ再割り当てされることはありません。

ログイン、報酬取得、残高更新、CAPTCHA取得、送信、または履歴取得中にネットワークエラーが発生すると、アカウントは次に未使用で正常なプロキシへ切り替わります。プロキシプールが存在する場合、出金処理が直接IPへ密かにフォールバックすることはありません。重複操作のリスクを減らすため、切り替え中も取得リクエストIDと出金リクエストIDは変わりません。

アカウントごとに少なくとも 1 つの一意なプロキシを用意し、リトライ用に追加のプロキシも用意してください。プールを使い切った場合、現在のアカウントは失敗として処理され、次のアカウントへ進みます。

高度な信頼性とセキュリティのヒント

  • ストレージが適切に保護されていない限り、wallets-accounts.json を共有または同期された場所に置かないでください。
  • ウォレットを交換する前、またはインストール先を移動する前に、ウォレットシークレットを安全にバックアップしてください。
  • ready_task_ids は、実際に手動で完了したタスクにのみ使用してください。
  • アカウントプロキシが影響するのは ATF の HTTP リクエストであり、直接接続する Telegram MTProto 接続ではないことに注意してください。
  • 使用済みおよび失敗したプロキシはバッチ内で再利用されないため、十分な数の異なる出金用プロキシを設定してください。
  • 正常なシャットダウンには Ctrl+C を使用してください。ボットは接続をクリーンアップし、シャットダウンシグナルを受信した後に別のアカウントを開始しません。
  • アカウントごとの概要を確認してください。概要では、success、partial、failed の結果が区別されます。

このプロジェクトでは、allowed_hosts によって API と WebApp の接続先を制限し、HTTPS を必須としています。HTTP リダイレクトには自動的に従いません。HTTP 401 および 403 のレスポンスは再試行しませんが、HTTP 429 および 5xx のレスポンスにはジッター付きの指数バックオフを使用します。

リクエスト ID は再試行時も維持されるため、サーバーは繰り返された操作を冪等として扱えます。クールダウンや already claimed などのビジネスレスポンスは、ネットワーク障害として扱いません。ATF ログイン中に繰り返し失敗するプロキシは一時的に隔離され、ボットが直接 IP に無断で切り替えることはありません。

セッション トークン、初期化データ、ハッシュ、プロキシパスワードはログからマスキングされます。安定したデバイス ID は Telegram ID ごとに .state/device-ids.json へ保存されます。ボットは各サイクルで config.json、セッション、プロキシ、アカウントの上書き設定も再読み込みします。

マイニングでセキュリティ質問への回答が必要な場合、認識可能な基本算術は自動的に解答されます。不明な形式の場合は、手動のターミナル入力に切り替わります。

インストールを検証する

セットアップまたは設定変更後に、プロジェクトのチェックとテストを実行します。

npm run check
npm test

まとめ

ATF Bot Automation v2 は、新しい Telegram WebView 認証に加え、複数アカウントの ATF 自動化、TON ウォレット検証、動的タスク、紹介機能、アカウント監査、管理された出金を組み合わせています。有効な Telethon セッションと保護された Telegram 認証情報から開始し、少数のアカウントで主要なワークフローを検証してください。また、wallets-accounts.json には生成されたすべてのウォレットへ直接アクセスできる情報が含まれるため、高価値の秘密情報として扱ってください。