바이낸스 API 발급 완벽 가이드 — 모두 놓치는 보안 함정 4가지
"바이낸스 API 키 발급 자체는 검색하면 5분 만에 알 수 있는데, 왜 이 글이 필요한가?" — 답은 간단합니다. 발급 절차를 검색하면 나오지만, 발급 후 보안 설정의 차이로 자산이 0이 되는 사례가 매달 보고됩니다. 실제로 2024~2025년 바이낸스 한국 사용자 사이에서도 출금 권한을 켠 키가 유출되어 잔고가 인출된 사건이 여러 번 있었습니다.
이 가이드는 2026년 5월 기준 바이낸스 최신 화면을 그대로 따라가며, 각 단계마다 "이 옵션은 왜 이렇게 설정해야 하는지"를 함께 설명합니다. 처음 발급하시는 분은 이대로만 따라하면 안전합니다. 이미 운영 중이신 분도 끝에 정리된 보안 함정 4가지는 꼭 확인하세요.
이 글에서 다루는 것
- 발급 전 체크리스트 (KYC · 2FA · 고정 IP)
- 1단계 — API 관리 페이지 진입
- 2단계 — 키 유형 선택 (HMAC / Ed25519 / RSA)
- 3단계 — 키 이름(라벨) 정하기
- 4단계 — 권한 설정 (가장 중요)
- 5단계 — IP 화이트리스트 등록
- 6단계 — Secret 백업 및 저장
- 7단계 — Python으로 테스트 호출
- 모두 놓치는 보안 함정 4가지
- 자주 묻는 질문 (FAQ)
0. 발급 전 체크리스트
API 키 발급을 누르기 전에 다음 3가지가 준비되어 있어야 합니다. 없으면 발급 도중 막힙니다.
- KYC 레벨 1 완료 — 여권/신분증 + 셀카 인증. 미완료 계정은 API 메뉴 자체가 안 보입니다.
- 2단계 인증(2FA) 활성 — Google Authenticator 또는 SMS. 발급 시 자동 요구됩니다.
- 봇이 돌아갈 고정 IP — VPS, 클라우드, 사무실 고정 IP 중 하나. 가정용 인터넷은 IP가 바뀌므로 별도 대응이 필요합니다(아래 5단계 참고).
💡 한국 사용자 참고: 바이낸스는 2025년부터 한국에서 직접 가입이 제한적입니다. 기존 계정이 있다면 사용 가능하나, 신규 가입은 글로벌 도메인(binance.com) 접속 가능 여부를 먼저 확인하세요. 국내 거주자라면 업비트 또는 빗썸이 더 안정적인 선택입니다.
1API 관리 페이지 진입
로그인 후 우상단 프로필 아이콘 → Account → 좌측 메뉴에서 API Management 클릭. 또는 직접 URL로 이동: binance.com/en/my/settings/api-management
처음 진입 시 2FA 인증 1번 요구됩니다. 인증 완료 후 화면 우측의 "Create API" 버튼이 활성화됩니다.
2키 유형 선택 — HMAC, Ed25519, RSA
"Create API" 클릭 시 키 유형을 묻습니다. 2026년 현재 3가지 선택지가 있습니다.
| 유형 | 특징 | 2026년 추천 |
|---|---|---|
| System generated (HMAC SHA-256) | 가장 보편적. 모든 SDK 지원. Secret 분실 시 재발급 필요. | ✅ 호환성 최우선이면 추천 |
| Ed25519 | 2024년부터 도입. 서명 속도 약 3배, 키 길이 짧음, 보안 강도 ↑ | ✅ 2026년 신규 발급 1순위 |
| RSA | 일부 기관 SDK 호환용. 일반 봇 운영에는 과스펙. | ❌ 특별한 이유 없으면 비추 |
처음이라면 Ed25519를 선택하세요. python-binance, ccxt 등 메이저 라이브러리 모두 지원합니다.
3키 이름(라벨) 정하기 — "bot"은 금지
다음 화면에서 키 이름을 입력합니다. 흔히 "bot", "trading", "auto" 같은 일반명을 쓰는데, 키가 늘어나면 어떤 게 어디 쓰이는지 모릅니다.
알고랩 권장 네이밍 규칙:
# 형식: [용도]-[자산]-[환경]-[발급월]
ex)
grid-btc-prod-202605
arbitrage-eth-dev-202605
funding-spot-vps01-202605이렇게 하면 키가 10개 넘어가도 한눈에 구분되고, 사고 발생 시 어느 봇 키인지 즉시 파악됩니다.
4권한 설정 — 가장 중요한 단계
키 생성 직후 권한(Permissions) 화면이 나옵니다. 여기서 잘못 체크하면 보안 사고가 납니다. 최소 권한 원칙(Principle of Least Privilege)이 기본입니다.
| 권한 | 설명 | 설정 |
|---|---|---|
| Enable Reading | 잔고/주문/시세 조회. 기본 ON, 끌 수 없음. | ✅ ON (필수) |
| Enable Spot & Margin Trading | 현물·마진 주문 권한. | 현물봇이면 ON |
| Enable Futures | 선물(USDT-M, COIN-M) 주문 권한. | 선물봇이면 ON |
| Permits Universal Transfer | 지갑 간 내부 이동(Spot↔Futures). | 꼭 필요할 때만 ON |
| Enable Withdrawals | 외부 주소로 출금. | ❌ 절대 OFF 유지 |
| Symbol Restriction | 특정 심볼(예: BTCUSDT)만 거래 허용. | 가능하면 ON (해킹 시 피해 최소화) |
⚠️ 절대 켜지 말 것: Enable Withdrawals
자동매매 봇에서 외부 출금이 필요한 경우는 거의 없습니다. 이 권한이 켜진 키가 한 번이라도 깃허브, 디스코드, 텔레그램 채팅에 노출되면 봇이 자산을 모두 외부 주소로 송금합니다. 회복 불가능합니다. 정 필요하면 별도 키로 분리하고 출금 화이트리스트(받는 주소)도 함께 등록하세요.
5IP 화이트리스트 등록 — 보안의 핵심
같은 권한 화면 하단에 "Restrict access to trusted IPs only (Recommended)" 옵션이 있습니다. 반드시 체크 후 봇이 돌아갈 IP를 입력하세요.
봇 서버의 외부 IP 확인:
# 봇이 돌아갈 서버에서 실행
curl ifconfig.me
# 또는
curl ipinfo.io/ip여러 IP를 동시에 등록하려면 콤마로 구분: 1.2.3.4, 5.6.7.8 (최대 20개)
가정용 인터넷이라 IP가 자주 바뀌는 경우
- VPS 사용 권장: Vultr, AWS Lightsail, Oracle Free Tier 등 월 $5~10면 24시간 고정 IP 확보.
- 가정 IP 사용 시: ISP에 "고정 IP 신청" 가능(월 수천 원 추가). 또는 라우터에서 외부 IP 변경 감지 → API 화이트리스트 자동 업데이트 스크립트 운영(비추, 위험).
✅ 화이트리스트의 보너스 효과: IP 화이트리스트가 설정된 키는 90일 자동 만료가 적용되지 않습니다. 즉 봇이 90일마다 중단되는 사태를 방지합니다.
6Secret 백업 — 한 번만 보입니다
생성 완료 화면에 API Key와 Secret Key가 나옵니다. Secret은 이 화면을 닫으면 영원히 다시 볼 수 없습니다(바이낸스 정책상 평문 저장 안 함).
보관 방법(권장 순):
- 패스워드 매니저(1Password, Bitwarden) — 가장 안전
- VPS 환경변수(
.env파일,.gitignore필수) — 봇용 표준 - 로컬 암호화 파일(
age또는gpg) — 오프라인 백업
❌ 금지: 메모장, 카톡 자기에게 보내기, 코드에 하드코딩, 깃허브 커밋
# .env 예시 (.gitignore 에 .env 추가 필수)
BINANCE_API_KEY=abcd1234...
BINANCE_API_SECRET=wxyz5678...
# Python에서 사용
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("BINANCE_API_KEY")
api_secret = os.getenv("BINANCE_API_SECRET")7Python으로 테스트 호출
발급 직후 키가 제대로 작동하는지, 권한이 의도대로 설정됐는지 확인합니다. python-binance 라이브러리 사용:
pip install python-binance python-dotenvfrom binance.client import Client
import os
from dotenv import load_dotenv
load_dotenv()
client = Client(os.getenv("BINANCE_API_KEY"), os.getenv("BINANCE_API_SECRET"))
# 1. 서버 연결 확인
print(client.ping()) # {} 가 나오면 정상
# 2. 계정 정보 조회 (Read 권한 확인)
account = client.get_account()
print("계정 권한:", account.get("permissions"))
# ['SPOT'] 또는 ['SPOT', 'FUTURES'] 등이 나옴
# 3. 잔고 (0 아닌 것만)
balances = [b for b in account["balances"] if float(b["free"]) > 0]
print("보유 자산:", balances)
# 4. (선물봇 한정) 선물 권한 확인
try:
futures_account = client.futures_account()
print("선물 잔고:", futures_account["totalWalletBalance"], "USDT")
except Exception as e:
print(f"선물 권한 없음 또는 오류: {e}")위 코드가 에러 없이 돌면 발급 성공입니다. get_account()에서 "permissions" 필드가 의도한 권한(SPOT/MARGIN/FUTURES)과 일치하는지 꼭 확인하세요.
모두 놓치는 보안 함정 4가지
함정 1. IP 화이트리스트 없는 키 = 시한폭탄
"개발 단계라 일단 화이트리스트 없이 발급"하는 경우가 흔합니다. 그런데 그 키가 개발자 노트북, 깃허브, 슬랙 채널, 디스코드 봇을 거치며 의도치 않게 노출됩니다. 화이트리스트가 없으면 노출 즉시 해커가 쓸 수 있습니다.
해결: 개발 단계여도 본인 노트북 IP라도 등록하세요. IP는 클릭 1번으로 바꿀 수 있습니다.
함정 2. 한 키로 여러 봇 운영
키 1개로 그리드봇, 차익봇, 알람봇을 모두 돌리면 한 봇에서 에러 났을 때 전체 키 정지(예: rate limit ban)가 다른 봇까지 멈춥니다. 또한 사고 발생 시 어느 봇에서 비롯됐는지 추적이 어렵습니다.
해결: 봇마다 별도 키. 라벨에 봇 이름을 명시(3단계 참고).
함정 3. Secret을 코드 리포에 커밋
가장 흔한 사고 유형. git status에 .env가 보이는데 무심코 git add . → git push. 5분 안에 봇이 해커 자산으로 변신합니다. 깃허브 시크릿 스캐너가 자동으로 노출된 키를 인덱싱하기 때문입니다.
해결:
.gitignore에.env,*.key,secrets/추가- git-secrets 또는 gitleaks pre-commit 훅 설치
- 이미 커밋했다면 즉시 키 폐기 + 재발급(히스토리 삭제로는 부족, 깃허브가 이미 인덱싱)
함정 4. 90일 만료 정책을 잊고 봇 방치
IP 화이트리스트 없는 키는 발급 90일 후 자동 만료됩니다. 봇 운영자는 "어느 날 갑자기 봇이 멈춤" → 로그 확인 → 인증 에러 → 그제서야 만료를 깨닫습니다. 이 사이 매매 기회 손실 또는 손절 미체결로 더 큰 손실 발생.
해결:
- 처음부터 IP 화이트리스트 등록 → 만료 면제
- 봇에 "API 키 만료 임박 알림"(매일 자정
get_account()호출 → 401 발생 시 텔레그램 알림)
발급 후 첫 운영 체크리스트
- ☐
get_account()호출 성공 - ☐ permissions 필드가 의도한 권한과 일치
- ☐ IP 화이트리스트 등록 완료, 외부 PC에서 호출 시 차단되는지 확인
- ☐ Secret이 깃 리포에 없음(
git status확인) - ☐ 출금 권한 OFF 확인(API Management 화면 재확인)
- ☐ 키 라벨에 봇 이름·환경·발급월 포함
- ☐ 테스트 주문 1건 → 즉시 취소(주문 흐름 확인)
보태기 — 발급 다음, 첫 호출에서 막히는 에러 3가지
키를 제대로 만들었는데도 첫 호출이 실패하는 경우가 대부분입니다. 원인은 거의 세 가지 에러코드로 수렴합니다. 바이낸스는 실패 시 code와 msg를 담은 JSON을 돌려주므로, 그 숫자만 보면 원인을 바로 특정할 수 있습니다.
-2015 — 키·IP·권한 중 하나가 어긋났다
{"code":-2015,"msg":"Invalid API-key, IP, or permissions for action."}이름 그대로 세 가지가 한 코드로 묶여 있어서 헷갈립니다. 점검 순서는 ① 키를 잘못 복사했는가(앞뒤 공백·줄바꿈) → ② IP 화이트리스트에 지금 이 서버의 공인 IP가 들어 있는가 → ③ 하려는 동작에 맞는 권한(Enable Spot & Margin Trading 등)이 켜져 있는가. 실제로는 ②가 압도적으로 많습니다. 위 함정 1에서 다룬 화이트리스트를 등록해 두고, VPS를 옮기거나 재부팅해 IP가 바뀐 뒤 그대로 두면 이 에러가 납니다.
-1021 — 내 컴퓨터 시계가 어긋났다
{"code":-1021,"msg":"Timestamp for this request is outside of the recvWindow."}
바이낸스는 요청에 담긴 timestamp가 서버 시각과 recvWindow(기본 5,000ms) 안에 있어야 받아줍니다. 내 PC나 VPS의 시계가 몇 초만 밀려도 전부 거부됩니다. 해결은 두 갈래입니다.
# (1) 근본 처방 — OS 시간 동기화 (리눅스 예)
sudo timedatectl set-ntp true
# (2) 코드 처방 — 서버 시간과의 차이를 보정
import time, requests
def server_offset():
t0 = int(time.time() * 1000)
srv = requests.get("https://api.binance.com/api/v3/time").json()["serverTime"]
return srv - t0
OFFSET = server_offset()
params = {"timestamp": int(time.time() * 1000) + OFFSET,
"recvWindow": 5000} # 필요하면 늘리되 무한정은 불가
recvWindow를 무작정 키우는 것은 임시방편입니다. 시계를 맞추는 것이 정답이고, 값 상한은 정책에 따라 바뀔 수 있으니 공식 문서를 확인하세요.
-1022 — 서명이 틀렸다
{"code":-1022,"msg":"Signature for this request is not valid."}
바이낸스의 인증 요청은 쿼리스트링 전체를 Secret Key로 HMAC SHA256 서명해 signature 파라미터로 붙이는 방식입니다. 여기서 사람들이 반복해서 틀리는 지점은 셋입니다.
- 서명한 문자열과 실제로 보낸 문자열이 다르다 — 파라미터 순서를 바꾸거나 인코딩을 다시 하면 서명이 깨집니다. 서명한 그 문자열을 그대로 보내야 합니다.
signature는 맨 끝에 붙입니다. 서명 대상에 자기 자신이 들어가면 안 됩니다.- API Key는 헤더, Secret은 서명에만 씁니다. Secret을 쿼리로 보내면 안 됩니다.
import hmac, hashlib
from urllib.parse import urlencode
query = urlencode(params) # 서명할 문자열
sig = hmac.new(API_SECRET.encode(), query.encode(), hashlib.sha256).hexdigest()
res = requests.get("https://api.binance.com/api/v3/account?" + query + "&signature=" + sig,
headers={"X-MBX-APIKEY": API_KEY})
python-binance나 ccxt 같은 라이브러리를 쓰면 이 과정을 대신 처리해 주므로, 직접 서명하다 막힌다면 라이브러리로 갈아타는 것도 방법입니다.
덤 — 키가 멀쩡해도 막히는 경우: 호출 한도
발급·인증이 다 통과했는데도 운영 중에 갑자기 실패하기 시작한다면 호출 한도입니다. 바이낸스는 요청 수가 아니라 가중치(weight)로 세며, 응답 헤더 X-MBX-USED-WEIGHT-1M에 지금까지 쓴 양이 실려 옵니다. 한도를 넘으면 HTTP 429가 오고, 그 상태에서 계속 두드리면 HTTP 418 — IP 자동 차단으로 넘어갑니다. 차단은 반복될수록 길어지므로 429를 받은 순간 멈추고 물러서는(백오프) 로직이 반드시 있어야 합니다.
한도를 넘지 않게 설계하는 방법은 API 호출 제한 설계 — 바이낸스·업비트·KIS·키움 한도에서, 실시간 가격을 폴링 대신 스트림으로 받는 방향은 바이낸스 자동매매 봇 30분 안에 만들기에서 이어집니다.
3분 자가진단 — 에러코드가 -2015면 IP 화이트리스트부터, -1021이면 서버 시계부터, -1022면 서명 문자열부터 봅니다. 429가 뜨면 코드가 아니라 호출량 문제입니다. ※ 에러코드·메시지·한도값은 바이낸스 정책에 따라 변경될 수 있으므로 공식 API 문서에서 최신 내용을 확인하세요.
보태기 — 실전 키를 만들기 전에 연습할 곳이 있다
위 절차는 실제 돈이 걸린 키를 만드는 과정입니다. 그런데 코드가 아직 검증되지 않은 상태에서 실전 키부터 만들면, 서명 오류나 파라미터 실수를 진짜 잔고로 배우게 됩니다. 바이낸스는 무료 모의 환경을 제공하므로 인증·주문·에러 처리까지 여기서 먼저 통과시키는 것이 순서입니다.
주의할 점은 모의 환경이 하나가 아니라 두 갈래라는 것입니다.
현물은 https://testnet.binance.vision/api를 쓰고 GitHub 계정으로 로그인해 키를 받습니다.
선물 쪽은 2026-08-30 확인 기준으로 예전에 안내되던 testnet.binancefuture.com이
demo.binance.com으로 넘어가고, Demo Mode의 REST 주소는
https://demo-api.binance.com/api입니다.
두 환경은 실전과 계정이 분리되어 키가 호환되지 않습니다.
실전 키를 테스트넷 주소에 보내면 인증 실패가 아니라 -2015로 키 자체가 거절됩니다.
위에서 -2015의 원인 1순위로 IP 화이트리스트를 짚었는데,
모의 환경을 함께 쓰는 경우에는 "주소와 키의 짝"이 먼저 의심 대상입니다.
주소 전체 목록과 전환 방법은
바이낸스 테스트넷 API 발급 — 선물은 Demo Mode에 정리해 두었습니다.
다만 테스트넷에서 검증되는 것은 배관이지 전략이 아닙니다. 호가가 얇아 체결 가격이 실전과 다르고 잔고·주문 데이터가 주기적으로 초기화될 수 있으므로, 수익률을 여기서 판단하면 안 됩니다. 연결과 에러 처리를 여기서 끝내고, 성과는 소액 실계좌에서 따로 확인하십시오.
자주 묻는 질문
Q. KYC 안 하고 API 발급 가능한가요?
불가능합니다. 2024년 이후 바이낸스는 KYC 레벨 1 완료 계정만 API 메뉴 접근이 허용됩니다.
Q. 키 발급에 비용이 드나요?
무료입니다. 계정당 최대 30개까지 발급 가능. 거래 수수료는 별도(BNB 보유 시 25% 할인).
Q. API 키가 만료되면 봇이 멈추나요?
IP 화이트리스트가 설정된 키는 만료되지 않습니다. 화이트리스트 없는 키만 90일 후 자동 만료입니다. 만료를 막으려면 처음부터 IP 등록을 권장합니다.
Q. 미국 IP에서 한국 IP로 옮기면 화이트리스트는 어떻게 하나요?
API Management → 해당 키 → Edit → 새 IP 추가/삭제. 변경 시 2FA 재인증 요구됩니다. 봇 IP가 바뀔 가능성이 있다면 미리 여러 IP를 등록해두면 됩니다.
Q. 출금 권한 안 켜면 정말 안전한가요?
출금은 막히지만 거래로 자산을 망가뜨릴 수 있습니다(예: 의도적으로 큰 슬리피지 주문). Symbol Restriction을 함께 켜면 안전성이 한 단계 더 올라갑니다.
Q. Ed25519와 HMAC 중 무엇을 쓰면 좋나요?
2026년 신규 발급은 Ed25519 추천. 서명 속도가 3배 빠르고 키 길이가 짧으며, 메이저 SDK(python-binance, ccxt)는 모두 지원합니다. 기존에 HMAC 코드를 다 만들어둔 상태면 굳이 바꿀 필요는 없습니다.
마무리
바이낸스 API 발급 자체는 어렵지 않지만, 발급 후 보안 설정의 차이가 봇의 생존을 결정합니다. 위 4가지 함정만 피해도 알고랩이 80건+ 제작하며 본 사고의 90% 이상이 예방됩니다.
이미 발급된 키가 있다면 지금 바로 API Management로 가서:
- 출금 권한 OFF 확인
- IP 화이트리스트 등록
- 키 라벨 정리
이 3가지만 점검하셔도 즉시 보안 수준이 올라갑니다.