1. 학습 목표
본 강의의 목표는 국내 최대 가상자산 거래소인 Upbit의 API를 활용하여, 사용자가 설정한 특정 가격에 도달했을 때 자동으로 코인을 매수하거나 매도하는 파이썬 트레이딩 봇을 구축하는 것입니다. 이 과정을 통해 API 통신 원리, 실시간 데이터 파싱, 그리고 실제 주문 집행 로직을 실무 수준에서 완벽하게 습득하게 됩니다. 단순한 이론을 넘어 2026년 현재 가장 안정적인 라이브러리를 사용하여 즉시 배포 가능한 코드를 작성하는 것이 핵심입니다.
2. 사전 준비 사항
실습을 진행하기 전, 아래의 환경이 갖춰져 있어야 합니다. 본 튜토리얼은 2026년 기준 최신 안정화 버전을 바탕으로 구성되었습니다.
- 운영체제(OS): Windows 11, macOS Sequoia, 또는 Ubuntu 24.04 이상
- 개발 도구: VS Code (Visual Studio Code) 최신 버전 권장
- 언어 버전: Python 3.10.x 이상 (3.12 버전 권장)
- 필수 라이브러리:
pyupbit: Upbit API를 추상화하여 쉽게 사용할 수 있게 해주는 핵심 라이브러리pandas: 데이터 처리 및 분석용python-dotenv: API 키 보안 관리를 위한 환경 변수 로드용
- 터미널 설치 명령어:
pip install pyupbit pandas python-dotenv - 준비물: Upbit API Key (Open API 관리 페이지에서 Access Key와 Secret Key 발급 필요)
3. Upbit API 키 발급 및 보안 설정
자동 매매 봇을 만들기 위해서는 Upbit 서버에 명령을 내릴 수 있는 권한이 필요합니다. Upbit 로그인 후 [마이페이지] -> [Open API 관리]에서 키를 발급받으세요. 이때 반드시 ‘자산조회’, ‘주문하기’ 권한을 체크해야 하며, 본인의 IP 주소를 등록하여 보안을 강화해야 합니다.
환경 변수 설정 (.env 파일)
API 키를 소스 코드에 직접 입력하는 것은 매우 위험합니다. 프로젝트 루트 폴더에 .env 파일을 생성하고 다음과 같이 저장하세요.
UPBIT_ACCESS_KEY='내_액세스_키_입력'
UPBIT_SECRET_KEY='내_시크릿_키_입력'4. 단계별 실습 과정: 기초 로직 설계
단계 1: API 연결 확인 및 잔고 조회
가장 먼저 API가 정상적으로 작동하는지 확인하기 위해 본인의 계좌 잔고를 출력하는 코드를 작성합니다. 이 과정이 통과되어야 다음 단계인 매매 로직으로 넘어갈 수 있습니다.
import pyupbit
import dotenv
import os
# 환경 변수 로드
dotenv.load_dotenv()
access = os.getenv('UPBIT_ACCESS_KEY')
secret = os.getenv('UPBIT_SECRET_KEY')
# Upbit 객체 생성
upbit = pyupbit.Upbit(access, secret)
# 잔고 조회 (KRW-BTC 예시)
print("내 잔고:", upbit.get_balance("KRW"))
단계 2: 특정 가격 감시 로직 구현
봇의 핵심은 ‘무한 루프’를 돌며 현재가를 체크하는 것입니다. pyupbit.get_current_price 함수를 사용하여 실시간 시세를 가져오고, 설정한 목표가와 비교합니다.
단계 3: 자동 매수/매도 주문 함수 작성
가격 조건이 충족되었을 때 시장가로 즉시 주문을 실행하는 로직을 포함합니다. 안전을 위해 주문 성공 여부를 출력하고 루프를 종료하거나 대기 상태로 전환합니다.
5. 전체 소스 코드: ‘Target Price Bot’
아래는 비트코인(BTC)이 사용자가 설정한 가격 이하로 떨어지면 매수하고, 특정 수익률에 도달하면 매도하는 통합 예제 코드입니다.
import pyupbit
import time
import dotenv
import os
# 1. 환경 설정 및 로그인
dotenv.load_dotenv()
upbit = pyupbit.Upbit(os.getenv('UPBIT_ACCESS_KEY'), os.getenv('UPBIT_SECRET_KEY'))
# 2. 매매 설정 값
target_ticker = "KRW-BTC" # 대상 코인
buy_target_price = 95000000 # 매수 목표가 (예: 9,500만원)
sell_target_price = 105000000 # 매도 목표가 (예: 1억 500만원)
buy_amount = 10000 # 매수 금액 (단위: KRW, 최소 5,000원 이상)
print(f"{target_ticker} 자동 매매 봇을 시작합니다.")
while True:
try:
# 현재가 조회
current_price = pyupbit.get_current_price(target_ticker)
print(f"현재가: {current_price}원 | 매수목표: {buy_target_price}원")
# 매수 로직: 현재가가 목표가보다 낮고 잔고가 있을 때
krw_balance = upbit.get_balance("KRW")
if current_price <= buy_target_price and krw_balance > buy_amount:
res = upbit.buy_market_order(target_ticker, buy_amount)
print("매수 주문 완료:", res)
break # 실습을 위해 매수 후 종료 (반복 가능)
# 매도 로직: 보유 수량이 있고 현재가가 매도 목표가 이상일 때
coin_balance = upbit.get_balance(target_ticker)
if coin_balance > 0 and current_price >= sell_target_price:
res = upbit.sell_market_order(target_ticker, coin_balance)
print("매도 주문 완료:", res)
break
time.sleep(1) # API 요청 과부하 방지 (1초 대기)
except Exception as e:
print("에러 발생:", e)
time.sleep(1)6. 결과 확인 및 디버깅
코드를 실행하면 터미널에 실시간으로 현재가가 출력됩니다. 설정한 가격에 도달하는 순간, Upbit 앱에서 ‘체결 알림’이 오는지 확인하세요. buy_market_order는 시장가 매수이므로 즉시 체결됩니다.
주요 체크 리스트
- 최소 주문 금액: Upbit의 최소 주문 금액은 보통 5,000원입니다. 잔고가 이보다 적으면 에러가 발생합니다.
- API 호출 제한: 초당 호출 횟수가 제한되어 있으므로 반드시
time.sleep()을 사용하여 적절한 간격을 두어야 합니다. - 네트워크 상태: 서버 환경(AWS, Google Cloud 등)에서 구동할 경우 24시간 중단 없는 모니터링이 가능합니다.
7. 주의 사항 및 향후 확장성
본 튜토리얼에서 다룬 봇은 가장 기초적인 ‘가격 지정’ 방식입니다. 실제 실무에서는 다음과 같은 기능을 추가하여 고도화할 수 있습니다.
- 변동성 돌파 전략: 전일 고가와 저가의 범위를 계산하여 돌파 시 매수하는 전략 적용.
- 슬랙(Slack) 알림: 주문 체결 시 메시지를 본인의 스마트폰으로 전송하는 기능.
- 기술적 지표 활용: RSI, MACD, 이동평균선 등을
pandas로 계산하여 매매 시점 정밀화.
가상자산 투자는 원금 손실의 위험이 있으므로, 반드시 소액으로 충분한 테스트를 거친 후 실전 투자에 임하시기 바랍니다. 이제 여러분은 자신만의 커스텀 트레이딩 봇을 가질 수 있는 기초 역량을 갖추었습니다. 실무 코딩의 핵심은 끊임없는 테스트와 예외 처리임을 잊지 마세요.