CryptoVolumeBot: 바이낸스 선물 거래량/가격 급등 알림 봇 설치 및 사용법

v1Bot.py

0.04MB

이 문서는 바이낸스 USDⓈ-M 선물 시장의 거래량 급등과 가격 변동을 실시간으로 감지하여 Telegram으로 알림을 보내는 Python 기반 Telegram 봇, CryptoVolumeBot의 설치와 사용 방법을 상세히 설명합니다. 이 봇은 사용자별 설정을 지원하며, 관리자 승인 시스템과 최대 10명(관리자 제외)의 사용자 제한을 포함합니다. 웹소켓을 통해 바이낸스 데이터를 수집하고, 알림 메시지에는 탈퇴 버튼이 포함되어 편리하게 관리할 수 있습니다.

1. CryptoVolumeBot 개요

• 주요 기능:
  • 바이낸스 선물 시장의 5분봉 데이터를 기반으로 거래량 급등(평균 대비 설정 배율 이상)과 가격 변동(설정 임계값 % 이상)을 감지.
  • 사용자별로 종목, 배율/임계값, 쿨다운 시간을 설정 가능.
  • 관리자 승인 시스템: 신규 사용자는 관리자의 승인 후 사용 가능.
  • 탈퇴 기능: 알림 메시지의 버튼으로 설정 삭제 및 탈퇴.
  • 관리자 전용 명령어: 사용자 승인, 대기/승인된 사용자 목록 확인.
• 기술 스택:
  • Python 3.12.3 이상.
  • 라이브러리: python-telegram-bot, websocket-client, httpx, python-dotenv.
  • 바이낸스 웹소켓 API (wss://fstream.binance.com) 및 REST API.
  • Telegram Bot API.
• 운영 환경: 로컬 PC, 서버, 또는 VPS(AWS, Heroku 등)에서 24/7 실행 가능.

2. 설치 방법

이 봇을 실행하려면 Python 환경과 몇 가지 설정이 필요합니다. 단계별로 설치 과정을 설명합니다.

2-1. 필수 요구사항

• Python 설치: Python 3.12.3 이상 (공식 사이트).
• 필수 라이브러리:
  • python-telegram-bot: Telegram API 연동.
  • websocket-client: 바이낸스 웹소켓 연결.
  • httpx: 바이낸스 REST API 요청.
  • python-dotenv: 환경 변수 관리.
• Telegram 봇 토큰: Telegram의 @BotFather를 통해 봇을 생성하고 API 토큰을 발급받으세요.
• 관리자 Telegram ID: 관리자의 Telegram ID(숫자)를 확인하세요. @userinfobot으로 확인 가능.
• 인터넷 연결: 바이낸스 웹소켓(wss://fstream.binance.com)과 API(https://fapi.binance.com)에 접근 가능해야 합니다.

2-2. 라이브러리 설치

터미널(또는 명령 프롬프트)에서 다음 명령어를 실행하여 필요한 라이브러리를 설치합니다:

pip install python-telegram-bot websocket-client httpx python-dotenv

가상 환경 사용(권장):

python -m venv myenv
source myenv/bin/activate  # Windows: myenv\Scripts\activate
pip install python-telegram-bot websocket-client httpx python-dotenv

2-3. 환경 변수 설정 (.env 파일)

1. 프로젝트 디렉토리에 .env 파일을 생성합니다.
2. 다음 내용을 추가하세요:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   TELEGRAM_ADMIN_ID=your_admin_telegram_id
   

   • TELEGRAM_BOT_TOKEN: BotFather에서 발급받은 토큰.
   • TELEGRAM_ADMIN_ID: 관리자의 Telegram ID (숫자).
3. 보안 주의: .env 파일을 GitHub 등에 업로드하지 마세요.

2-4. 스크립트 저장

• 제공된 Python 코드를 v1Bot.py로 저장하세요.
• 설정 파일(user_settings.json)은 최초 실행 시 자동 생성됩니다.

2-5. 봇 실행

터미널에서 다음 명령어로 실행:

python v1Bot.py

• 로그 확인: "텔레그램-바이낸스 선물 봇 스크립트 시작" 메시지가 출력되면 정상.
• 백그라운드 실행 (Linux):

  nohup python v1Bot.py &
  

  또는 tmux/screen 사용 권장.
• 24/7 실행: VPS(AWS, Heroku 등)에서 실행하여 지속적인 운영 보장.

2-6. 문제 해결

• 오류 로그: 콘솔 로그를 확인하여 "웹소켓 오류"나 "API 요청 오류"를 디버깅.
• SSL 문제: Python의 SSL 설정 확인 또는 방화벽 점검.
• 바이낸스 API 제한: IP 차단 시 VPN 사용 고려.
• 설정 파일 오류: user_settings.json이 손상되면 삭제 후 재실행(빈 파일로 초기화됨).

3. 사용 방법

봇은 Telegram 앱/웹에서 작동합니다. BotFather로 생성한 봇을 검색하여 시작하세요. 사용자는 일반 사용자와 관리자로 나뉘며, 모든 알림은 Markdown 형식으로 제공됩니다. 알림에는 "🚫 알림 중지 및 봇 사용 종료" 버튼이 포함되어 탈퇴가 가능합니다.

3-1. 일반 사용자 사용법

1) 봇 시작 및 승인 요청

• 명령어: /start
• 동작:
  • 신규 사용자: "환영합니다. 실시간 알람 사용을 위해 관리자의 승인이 필요합니다." 메시지 후 관리자에게 승인 요청 전송.
  • 승인 대기 중: "관리자의 승인을 기다리고 있습니다."
  • 승인된 사용자: 현재 설정 목록과 명령어 안내 표시.
• 출력 예시 (승인된 사용자):

  🤖 Crypto Spike Alert Bot 🤖
  바이낸스 선물 시장의 급등락을 실시간으로 알려드려요.
  
  🛰️ 현재 구독 설정
  🚀 거래량 알림:
    - BTCUSDT: 4배 (15분)
    - ETHUSDT: 3.5배 (10분)
  ⚡️ 가격 알림:
    - BTCUSDT: 0.35% (15분)
    - ETHUSDT: 0.45% (10분)
  
  🚀 거래량 알림 설정
  `/volume [종목] [배율(x)] [쿨타임(분)]`
  입력: `/volume BTCUSDT 4.5 15`
  삭제: `/volume BTCUSDT 0`
  
  ⚡️ 가격 변동 알림 설정
  `/price [종목] [등락값(%)] [쿨타임(분)]`
  입력: `/price ETHUSDT 0.36 10`
  삭제: `/price ETHUSDT 0`
  
  쿨다운: 알람 후 설정된 시간 동안 쿨다운 됩니다.
  

2) 거래량 급등 알림 설정 (/volume)

• 형식: /volume [종목] [배율] [쿨다운(분)]
• 예시:
  • /volume BTCUSDT 4.5 15: BTCUSDT의 거래량이 최근 2개 5분봉 평균의 4.5배 이상이면 15분 쿨다운으로 알림.
  • /volume BTCUSDT 0: 설정 삭제.
• 유효성:
  • 종목: 바이낸스 선물 심볼(예: BTCUSDT, ETHUSDT, 대소문자 무관).
  • 배율: 1.1 이상.
  • 쿨다운: 5분 이상 (삭제 시 제외).
• 알림 예시:

  🔥 BTCUSDT 거래량 급등! 🔥
  현재 5분 거래량: 1,234K
  평균 거래량 (2개 봉): 567K
  감지된 급등: 2.18배
  설정 배수: 4.5배
  가격 변동: 60,000.00 (+1.23%)
  알림 쿨타임: 15분
  [🚫 알림 중지 및 봇 사용 종료 🚫]
  

3) 가격 변동 알림 설정 (/price)

• 형식: /price [종목] [임계값(%)] [쿨다운(분)]
• 예시:
  • /price ETHUSDT 0.36 10: ETHUSDT의 가격이 0.36% 이상 변동 시 10분 쿨다운으로 알림.
  • /price ETHUSDT 0: 설정 삭제.
• 유효성:
  • 임계값: 0.1% 이상.
  • 쿨다운: 5분 이상 (삭제 시 제외).
  • 상승/하락 모두 감지.
• 알림 예시:

  🥑 ETHUSDT 가격 변동 감지! 🥑
  현재 가격: 3,000.00
  변동 가격 3,000.00 (+0.50%)
  이전 종가: 2,985.00
  설정 임계값: 0.36%
  쿨다운: 10분
  [🚫 알림 중지 및 봇 사용 종료 🚫]
  

4) 탈퇴 및 알림 중지

• 방법: 알림 메시지의 "🚫 알림 중지 및 봇 사용 종료" 버튼 클릭.
• 동작:
  • 모든 설정 삭제 및 봇 탈퇴 (관리자는 설정만 삭제).
  • 출력: "✅ 봇 사용 종료 및 설정 삭제 완료\n다시 사용을 원하시면 /start를 입력해 주세요."
• 자동 탈퇴: 모든 알림 설정 삭제 시 일반 사용자는 자동 탈퇴(관리자 제외).

5) 주의사항

• 종목은 USDT 기반 선물만 지원.
• 알림은 20초마다 체크(5분봉 기반).
• 승인되지 않은 사용자는 명령어 사용 불가.
• 최대 사용자 10명 제한(관리자 제외).

3-2. 관리자 사용법

관리자(환경 변수 TELEGRAM_ADMIN_ID)는 일반 사용자 기능 외에 다음 명령어를 사용 가능합니다.

1) 사용자 승인 (/approve)

• 형식: /approve [user_id]
• 예시: /approve 123456789
• 대안: 승인 요청 메시지의 "✅ 승인" 버튼 클릭.
• 출력: "✅ 사용자 123456789가 승인되었습니다."

2) 대기 사용자 목록 (/pending)

• 명령어: /pending
• 출력:

  ⏳ 승인 대기 중인 사용자 목록:
  • 사용자명: John Doe (@johndoe)
    - ID: 123456789
    - 승인 명령어: /approve 123456789
  

3) 모든 사용자 목록 (/users)

• 명령어: /users
• 출력:

  🐳 모든 사용자 목록
  (최대 사용자 수: 10, 현재: 3명)
  
  ⏳ 승인 대기 중인 사용자:
  • 123456789: John Doe (@johndoe)
  
  😄 승인된 사용자:
  • 987654321: Jane Smith (@janesmith)
  

4) 관리자 특이사항

• 탈퇴 버튼 클릭 시 설정만 삭제되고 봇에서 제거되지 않음.
• 사용자 차단 시 자동 삭제(메시지 전송 실패 시).

4. 추가 팁 및 문제 해결

• 알림 로직:
  • 거래량: 최근 2개 5분봉 평균 대비 설정 배율 이상.
  • 가격: 현재 5분봉의 변동률(상승/하락) 기준 설정 임계값 이상.
  • 쿨다운: 중복 알림 방지.
• 로그 확인: 콘솔 로그로 웹소켓 연결 상태, 오류 등 모니터링.
• 커스터마이징:
  • MAX_USERS 수정으로 사용자 제한 변경.
  • 알림 메시지 형식 변경(코드 수정 필요).
• 문제 해결:
  • "승인되지 않은 사용자": 관리자에게 승인 요청 문의.
  • 웹소켓 연결 실패: 인터넷 연결, 방화벽, 또는 바이낸스 서버 상태 확인.
  • 종목 오류: 바이낸스 API로 유효한 심볼 확인 (Exchange Info API).
  • 설정 파일 손상: user_settings.json 삭제 후 재실행.
• 테스트: 소규모로 실행 후 /start로 설정 확인.

5. 결론

CryptoVolumeBot은 바이낸스 선물 시장의 실시간 모니터링을 위한 강력한 도구입니다. 간단한 설치와 직관적인 Telegram 인터페이스로 거래량과 가격 급등을 빠르게 파악할 수 있습니다. VPS에서 실행하면 24/7 안정적인 알림을 받을 수 있으며, 관리자 시스템으로 사용자 관리가 용이합니다. 추가 질문이나 커스터마이징 요청은 언제든 Telegram으로 문의하세요!