AI 튜토리얼

Node.js와 Telethon 세션으로 ATF 텔레그램 미니 앱 자동화하기

이 튜토리얼에서는 ATF Bot Automation v2 설치, 텔레그램 인증 정보 구성, Telethon 세션 로드, TON 지갑 생성 및 확인, 대화형 또는 무인 워크플로 실행 방법을 설명합니다. 또한 작업 워커, 추천인 등록, Turnstile 솔버, 프록시, 대시보드, 출금, 재시도 및 필수 보안 정보 관리 주의사항도 다룹니다.

2026년 10월 2일약 20분 소요

Node.js와 Telethon 세션으로 ATF 텔레그램 미니 앱 자동화하기

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 프런트엔드 구성을 분석하여 동적 작업을 검색합니다.
각 세션마다 독립적인 작업 워커와 온보딩 상태를 유지합니다.
Turnstile 처리를 포함하여 Telegram messages.StartBot을 통해 추천인을 등록합니다.
ATF 요청에 계정별 HTTP 또는 HTTPS 프록시 구성을 사용할 수 있습니다.
실시간 자동화를 위한 Textual 대시보드와 별도의 읽기 전용 통계 대시보드를 제공합니다.
잔액 확인, 이미지 CAPTCHA 해결, 프록시 순환 및 출금 내역 보고를 포함한 순차적 출금을 지원합니다.
안정적인 요청 ID, 제어된 재시도, 정상적인 종료 및 로그 내 민감한 값 필터링을 지원합니다.

요구 사항

프로젝트를 설치하기 전에 다음을 준비하세요.

Node.js 22.5 이상.
https://my.telegram.org/apps에서 발급받은 본인의 Telegram API ID 및 API 해시.
.session으로 끝나는 활성 Telethon SQLite 세션 파일 하나 이상.
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] 봇 실행
[2] 추천인 코드로 계정 등록
[3] TON 지갑 교체
[4] 계정 통계 확인
[5] ATF 출금
[0] 종료

주요 자동화 실행

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 필드를 확인합니다. 인증된 지갑이 없으면 다음 순서로 진행합니다.

메인넷용 TON v4r2 지갑을 생성합니다.
생성 즉시 지갑 주소, 24단어 니모닉, 개인 키를 wallets-accounts.json에 저장합니다.
ATF에 공식 TON Proof 페이로드를 요청합니다.
ATF WebApp 도메인에 대한 Proof에 서명합니다.
Proof를 sync_wallet에 제출합니다.
검증이 성공한 후에만 보안 질문과 채굴을 계속합니다.

지갑 레코드는 검증이 시작되기 전에 기록됩니다. 따라서 일시적인 busy 응답이나 지연된 계정으로 인해 새로 생성된 지갑이 손실되지 않습니다.

지갑이 아직 검증되지 않은 상태에서 ATF가 busy 또는 캐시된/중복 제거된 응답을 반환하면, 메인 프로세스는 wallet_busy_retry_seconds 후 한 번 재시도합니다. 기본값은 15초입니다. 계정이 계속 사용 중이면 지갑 워커로 이동하여 메인 프로세스가 계속 진행할 수 있도록 합니다.

최대 wallet_worker_concurrency개의 지갑 작업이 병렬로 실행되며, 기본값은 10입니다. 추가 계정은 FIFO 대기열에 들어갑니다. 각 세션에는 활성 상태이거나 대기 중인 지갑 워커가 하나만 허용됩니다.

생성된 지갑은 실제 지갑 주소이지만, 온체인 트랜잭션에 사용되기 전까지는 블록체인에 배포되지 않습니다. wallets-accounts.json을 안전하게 보관하고 신중하게 백업하세요. 이 파일을 가진 사람은 누구나 지갑을 제어할 수 있습니다.

encrypted_secrets가 포함된 이전 레코드는 봇이 처음 열 때 평문 형식으로 마이그레이션됩니다. 이전의 WALLET_KEYSTORE_PASSWORD는 해당 마이그레이션에만 필요합니다.

계정별 재정의 적용

개별 세션에 서로 다른 설정이 필요한 경우 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는 수동으로 실제 완료한 일회성 작업을 식별하며, 이제 봇이 해당 작업을 요청할 수 있습니다.

재정의 파일, 프록시, 환경 파일, 캐시, 상태 파일 및 세션 파일은 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 보유량, 채굴 잔액, 정지 상태, 위험 점수, 적격 DEX 구매 상태, 대기 중인 출금, 최신 출금 상태 및 masked_auto_fraud의 FRAUD MASK가 표시됩니다. 출금 상태에는 NONE, PENDING, APPROVED, KYC/VERIFY, FAILED, UNAVAILABLE이 포함됩니다. KYC 상태와 사기 마스크는 서로 별개의 신호입니다.

r을 누르면 감사를 다시 실행하고, q를 누르면 종료합니다.

ATF 출금

옵션 5는 계정을 순차적으로 처리하며, 출금 요청마다 서버에서 70 ATF를 청구하므로 시작 전에 한 번 확인을 요청합니다.

각 계정에 대해 봇은 다음을 수행합니다.

새 세션으로 로그인한 후 mined_balance와 pending_reward를 읽습니다.
대기 중인 보상을 모두 클레임합니다.
다시 로그인하여 채굴 잔액을 새로 고칩니다.
잔액이 500 ATF 미만이거나 지갑이 인증되지 않은 경우 계정을 건너뜁니다.
출금 가능한 전체 채굴 잔액을 소수점 이하 4자리로 내림합니다.
이미지 CAPTCHA를 해결하고 출금을 제출합니다.
출금 내역을 읽고 최종적으로 확인 가능한 상태를 보고합니다.

ImageToTextTask 솔버를 사용하려면 .env에 2Captcha 키를 추가합니다.

TWOCAPTCHA_API_KEY=your_api_key

봇은 제출 전에 프런트엔드의 공식 1.2~2초 지터를 적용합니다. CAPTCHA 답변이 실패하거나 거부되면 새 챌린지를 요청하며, 재시도 횟수는 최대 3회인 withdraw_captcha_max_attempts와 서버의 attempts_left 중 더 작은 값으로 제한됩니다.

retry_after_seconds 응답, 출금 잠금 또는 서버 시도 횟수 소진이 발생하면 해당 계정에 대한 재시도를 중지합니다. 다음 명령으로 출금을 직접 실행합니다.

npm run withdraw

출금에 프록시 사용

proxy.txt 또는 proxies.txt에 프록시가 있으면 출금 모드는 전체 배치에 사용할 고유 풀을 생성합니다. 각 프록시는 실패하더라도 한 번만 선택할 수 있으며, 해당 배치 중 다른 계정에 재할당되지 않습니다.

로그인, 보상 클레임, 잔액 새로 고침, CAPTCHA 가져오기, 제출 또는 내역 조회 중 네트워크 오류가 발생하면 해당 계정은 사용되지 않은 다음 정상 프록시로 전환됩니다. 프록시 풀이 있으면 출금 모드는 직접 IP로 자동 전환되지 않습니다. 중복 작업 위험을 줄이기 위해 전환 중에도 클레임 및 출금 요청 ID는 변경되지 않습니다.

계정당 최소 하나의 고유 프록시와 재시도를 위한 추가 프록시를 제공하세요. 풀이 소진되면 현재 계정은 실패 처리되고 다음 계정의 처리가 계속됩니다.

고급 안정성 및 보안 팁

저장소가 적절히 보호되지 않는 한 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에는 생성된 모든 지갑에 직접 접근할 수 있는 정보가 포함되어 있으므로 매우 중요한 비밀 정보로 취급해야 합니다.