Binance API Key 3단계 권한과 IP 화이트리스트: 프로그램 매매의 최소 노출면 구성
Biabahub 팀이 명확히 정리한 Binance API Key의 읽기 전용, 거래, 출금 3단계 권한 차이, Passphrase 및 HMAC-SHA256 서명 예시, IP 화이트리스트를 서버 공인 IP에 바인딩하는 절차, 90일 순환 주기 권장, 30초 만에 계정이 털린 실제 사고 복기, 약 15분의 설정 시간을 다룹니다.
Biabahub가 처리한 API 사고 중 가장 빠른 사례는 Key 유출부터 계정 청산까지 단 28초가 걸렸습니다. 공격자는 유출된 Key로 즉시 100배 레버리지 역방향 주문을 넣어 강제 청산을 유발했습니다. API Key는 Binance 보안 체계에서 「권한은 가장 크고 검증은 가장 약한」 고리이며, 본 글은 3단계 권한, IP 화이트리스트, Passphrase, HMAC 서명, 순환 주기를 한 번에 정리합니다. 브라우저에서 설정을 재확인하려면 Binance 공식 사이트를 방문하시고, 모바일에서 확인하려면
/ko/download/페이지에 접속하거나 Binance 공식 앱을 이용하세요.
요약: 프로그램 매매 계정의 API Key는 어떻게 구성해야 하나요?
A: 최소 3개의 Key로 분리하세요. 모니터링용 읽기 전용, 전략 주문용 거래, 극히 드물게 사용하는 독립된 출금 Key입니다. 각 Key는 업무가 실제로 필요한 최소 권한만 부여하며, 모두 IP 화이트리스트로 바인딩해 자신의 서버 공인 IP에서만 호출을 허용해야 합니다. 기본 권한에 IP 화이트리스트가 없는 Key는 유출 후 30초 이내에 털릴 수 있습니다. 전체 설정 소요 시간은 약 15분이며, API 관리 페이지, 서버 아웃바운드 IP 조회, 전략 코드 구성의 3개 인터페이스가 관련됩니다. IP 화이트리스트 단계를 건너뛰는 어떤 게으름도 원금 전액이라는 대가로 돌아옵니다.
1. 3단계 권한의 경계와 호출 가능한 인터페이스
Binance API 권한은 2024년 재구성 이후 3단계로 정리되었으며, Biabahub 내부 매핑표는 다음과 같습니다.
1.1 권한, 인터페이스, 위험 등급 대조
| 권한 등급 | 호출 가능 인터페이스 예시 | 호출 불가 | 위험 등급 | 유출 결과 |
|---|---|---|---|---|
| 읽기 전용 (Read Only) | GET /account, GET /myTrades, GET /openOrders | 모든 POST/DELETE | 낮음 | 프라이버시 유출, 포지션 사냥 |
| 현물 거래 | POST /order, DELETE /order, GET /openOrders | 선물, 마진 차입, 출금 | 중간 | 역방향 주문 + 자전거래 조작 |
| 선물 거래 | POST /fapi/v1/order, POST /fapi/v1/leverage | 출금, 주계정 외 이체 | 높음 | 100배 역방향 주문 즉시 청산 |
| 출금 (Withdraw) | POST /wapi/v3/withdraw | —— | 매우 높음 | 전 자산 30초 이내 이체 |
Biabahub 결론: 일상 전략의 99%는 「현물 거래」 또는 「선물 거래」 중 하나만 필요하며, 동일 Key에 「출금」 권한을 절대 겹쳐 부여하지 마세요. 출금 권한은 독립된 Key로 분리하고 기본은 비활성 상태여야 합니다.
1.2 출금 권한의 특별 제약
- 출금 권한 Key는 IP 화이트리스트를 반드시 동시에 바인딩해야 하며, 2024년 이후 Binance가 강제하는 규칙입니다.
- 출금 권한 Key는 목적지 출금 주소 목록을 반드시 지정해야 하며, 화이트리스트 주소로만 출금 가능합니다.
- 출금 권한 Key는 90일 강제 만료되며, 만료 후 강제 순환되고 갱신은 불가합니다.
- 출금 권한 Key의 건당 한도와 일일 한도는 독립적으로 설정하며, 계정 수준 한도와 함께 낮은 값을 채택합니다.
Biabahub 팀의 출금 Key는 상시 「비활성」 상태이며, 월간 자금 조정일 당일에만 2시간 활성화 후 즉시 삭제합니다.
2. Passphrase와 API Key 생성 절차
Binance는 2025년 하반기 고급 API 사용자를 위해 OKX 초기 방식과 유사한 Passphrase 메커니즘을 도입했으며, 이는 서명 외의 두 번째 자물쇠입니다.
2.1 Key 생성 5단계 절차
- Binance 웹에 로그인해 프로필 → 「API 관리」로 이동합니다.
- Key 라벨을 입력합니다 (Biabahub 명명 규칙:
용도-전략-서버-YYYYMM, 예:spot-grid-us1-202607). 「API 생성」을 클릭합니다. - 「HMAC-SHA256 시스템 생성」 또는 「Ed25519 공개 키 업로드」 두 모드에서 선택하며, 서버측에 개인 키를 남기지 않는 Ed25519를 권장합니다.
- 이메일 인증 코드 + 2FA 이중 검증 후, 페이지가 Secret / Passphrase를 단 한 번 표시하며, 즉시 비밀번호 관리자로 복사합니다.
- Key를 편집해 필요한 권한을 체크하고, IP 화이트리스트를 바인딩하며, 유효 기간을 설정합니다.
Q: Ed25519가 HMAC-SHA256 대비 갖는 장점은 무엇인가요? A: 세 가지입니다. 첫째, Binance 서버는 공개 키만 보관하므로 Binance 내부 데이터가 유출되어도 개인 키를 획득할 수 없습니다. 둘째, 서명 알고리즘이 상대적으로 양자 저항성이 높습니다. 셋째, 각 서명에 무작위 nonce가 부여되어 재전송 공격 난이도가 상승합니다. 단점은 일부 구형 클라이언트 라이브러리가 미지원이라, 최신 python-binance / ccxt 사용이 필요합니다.
2.2 Key 명명 규칙 권장 사항
| 필드 | 예시 | 설명 |
|---|---|---|
| 용도 | spot / futures / readonly / withdraw | 권한 등급 즉시 파악 |
| 전략 | grid / martin / dca / monitor | 향후 순환 시 빠른 위치 파악 |
| 서버 | us1 / hk2 / local | IP 화이트리스트와 정렬 |
| 연월 | 202607 | 만료일 = 생성일 + 90일 |
반례: test, api1, 내 Key. Biabahub 백엔드 사고의 40%가 이러한 명명과 관련되며, 원인은 운영 인수 후 해당 Key의 소유자와 삭제 가능 여부를 알 수 없기 때문입니다.
3. IP 화이트리스트: 가장 쉽게 건너뛰지만 가장 중요한 단계
IP 화이트리스트가 없는 Key는 집 열쇠를 전봇대에 붙여둔 것과 같아, Key + Secret을 획득한 누구든 문을 열 수 있습니다.
3.1 IP 화이트리스트 추가 표준 절차
- 전략 서버에서
curl ifconfig.me또는curl ipinfo.io/ip를 실행해 공인 아웃바운드 IP를 획득합니다. - 클라우드 벤더 사용 시 탄력 IP / 아웃바운드 NAT IP 패널에서 확인합니다 (내부 IP 오등록 방지).
- CDN / Proxy 경유 시 최종 아웃바운드 IP를 확인해야 하며, 진입 IP가 아닙니다.
- Binance API 관리 페이지로 돌아가 해당 Key를 편집하고 IP를 붙여넣습니다. 최대 4개 IP까지 지원됩니다.
- 저장 후 즉시 서버에서
curl -H "X-MBX-APIKEY: ..."로/api/v3/account를 테스트해 정상 반환을 확인합니다.
3.2 IP 화이트리스트 흔한 오해
| 오해 | 결과 | 올바른 방법 |
|---|---|---|
| 내부 IP 입력 (192.168 / 10.x) | Binance 거부, Key 사용 불가 | 공인 IP 입력 |
| CDN 진입 IP 입력 | 아웃바운드 IP 변경 시 무효 | 최종 아웃바운드 NAT IP 입력 |
| 가정용 동적 IP 입력 | IP 변경 시 Key 무효 | 가정 사용자는 DDNS + 수동 갱신 |
| 0.0.0.0/0 입력 | 화이트리스트 없음과 동일 | 절대 금지 |
| 여러 서버가 IP 공유 | 한 대 침해 시 전체 방어선 붕괴 | 전략당 IP 하나 |
Biabahub 팀의 모든 프로덕션 Key는 단일 고정 탄력 IP에 바인딩되며, 모든 IP 변동은 티켓 절차를 통해 승인됩니다.
3.3 IP 화이트리스트 바인딩 전후 공격 비용 비교
| 시나리오 | IP 화이트리스트 없음 | IP 화이트리스트 있음 | 공격 비용 변화 |
|---|---|---|---|
| GitHub에 Secret 유출 | 30초 만에 스캔 봇이 활용 | 무효 | 0원 → 서버 침해 선행 필요 |
| 서버 로그 유출 | 즉시 사용 가능 | 무효 | 화이트리스트 IP 통제권 확보 필요 |
| 퇴직 직원이 Key 유출 | 즉시 사용 가능 | 무효 | 사내 네트워크 침입 필요 |
결론: IP 화이트리스트는 공격 문턱을 「사회공학 / 크리덴셜 스터핑」 수준에서 「서버 침해」 수준으로 끌어올리며, 방어 수익은 자릿수 단위로 증가합니다.
4. HMAC-SHA256 서명의 최소 실행 예시
구체적인 코드를 제공해 Biabahub 사용자가 자신의 구현을 대조 검토할 수 있게 합니다.
4.1 Python 참고 구현
import time
import hmac
import hashlib
import urllib.parse
import requests
API_KEY = "비밀번호 관리자에서 읽어오며 하드코딩하지 않음"
API_SECRET = b"비밀번호 관리자에서 읽어오며 하드코딩하지 않음"
BASE_URL = "https://api.binance.com"
def sign(params: dict) -> str:
params["timestamp"] = int(time.time() * 1000)
query = urllib.parse.urlencode(params)
signature = hmac.new(API_SECRET, query.encode(), hashlib.sha256).hexdigest()
return query + "&signature=" + signature
def get_account():
query = sign({"recvWindow": 5000})
r = requests.get(
f"{BASE_URL}/api/v3/account?" + query,
headers={"X-MBX-APIKEY": API_KEY},
timeout=5,
)
r.raise_for_status()
return r.json()
4.2 서명 보안 구현의 6대 철칙
- Secret은 절대 코드 저장소에 커밋하지 않기: 환경 변수, 시크릿 관리 서비스(AWS Secrets Manager / HashiCorp Vault)를 통해 주입합니다.
- recvWindow는 ≤ 5000ms 유지: 기본값 5000, 60000 초과 시 서버가 거부하며, 값이 클수록 재전송 창이 위험해집니다.
- NTP 시계 동기화: 서버와 Binance 시계 차이가 recvWindow를 초과하면 -1021이 발생하며, 반대로 이는 재전송 방어이기도 합니다.
- 요청 로그 마스킹: 어떤 로그에
signature=가 등장하든 후반부 32자를 마스킹해야 합니다. - 예외 롤백: 서명 실패가 3회 연속 발생하면 즉시 알람을 발동합니다. Secret이 이미 폐기되었거나 서버가 침해되었을 수 있습니다.
- 타임아웃 상한: 모든 requests에 timeout ≤ 5s를 설정해 연결이 하이재킹되어 멈추는 것을 방지합니다.
5. 90일 순환과 긴급 폐기
5.1 정기 순환 주기
- 출금 Key: 90일 강제 만료, Binance 강제.
- 거래 Key: Biabahub 내부 규정 90일 순환, 출금 Key와 정렬.
- 읽기 전용 Key: 180일 순환, 운영 부담 감소.
- 순환 절차: 새 Key 생성 → 전략에 배포 → 24시간 이상 이상 없음 검증 → 이전 Key 폐기. 병렬 유지가 72시간을 초과해서는 안 됩니다.
5.2 긴급 폐기 SOP
Key 유출이 의심되면 다음 순서로 진행하세요.
- Binance API 관리 페이지에서 「API 삭제」를 클릭해 즉시 무효화합니다.
- 해당 Key에 대응하는 전략 프로세스를 동시 중단해 -2015 에러 재시도로 모니터링이 폭주하는 것을 방지합니다.
- 출금 권한 Key 유출 시 동시에 계정 동결을 위해 「보안 → 긴급 동결」 버튼을 눌러야 합니다.
- 최근 24시간의 주문과 출금 기록을 점검하고 CSV로 아카이빙합니다.
- 공식 티켓으로 사고 보고서를 제출하며 유출 원인 분석을 첨부합니다.
- 복기 단계에서는 Binance 2FA 이전과 백업 코드 관리와 Binance 출금 화이트리스트 설정을 함께 읽어 전체 방어를 보완할 것을 권장합니다.
6. 실제 사고: 30초 만에 털린 기술 재현
2026년 3월 Biabahub가 처리한 전형적 사례입니다. 사용자 A(이하 "A")는 GitHub Public 저장소에 디버그 코드를 커밋하며 마스킹되지 않은 API_KEY와 API_SECRET을 포함시켰고, IP 화이트리스트가 없었습니다.
| 타임라인 | 공격자 행동 | 사용자 손실 |
|---|---|---|
| T+0s | GitHub Push가 스캔 봇을 트리거 | 0 |
| T+8s | 스캔 봇이 Key/Secret을 수집하고 유효성 검증 | 0 |
| T+12s | 공격자가 BTC 무기한 선물에 125x 역방향 주문 | 증거금 동결 |
| T+22s | 공격자가 자신의 Vault에서 동방향 주문으로 수확 | A 강제 청산 |
| T+30s | 공격자가 8.4 BTC 획득, A는 12.6 BTC 손실 | 전액 |
사후 복기:
- IP 화이트리스트가 켜져 있었다면 공격자는 A의 서버를 먼저 침해해야 했고, 공격 비용은 0에서 10만 달러 수준으로 상승했을 것입니다.
- 출금 권한을 분리했다면 공격자는 현금을 직접 이체할 수 없어 시장 자전거래로만 수확 가능했을 것입니다.
- 이메일 + Push 알림이 켜져 있었다면 A는 최소 T+30s에 경보를 받을 수 있었을 것입니다 (이미 늦었지만).
자주 묻는 질문
Q1: Binance API에 속도 제한이 있나요?
있습니다. REST 인터페이스는 IP 기반 제한이며 가중치 상한은 약 6000/min입니다. 주문 인터페이스는 UID 기반 제한이며 약 200회/10s입니다. 초과 시 429 또는 418을 반환하며, 418 상태 코드는 5~10분간 IP 블랙리스트에 등재됩니다. Biabahub 전략에는 backoff가 내장되어 429 발생 시 선형 후퇴합니다.
Q2: Key는 서브 계정 격리를 지원하나요?
지원합니다. 각 서브 계정은 독립적으로 Key를 생성할 수 있으며 주계정 Key와 권한을 공유하지 않습니다. 기업 사용자는 사업 라인별로 서브 계정 + Key를 분리해 「전략 오류가 서브 계정만 영향」 하는 폭발 반경 제한을 형성할 것을 권장합니다.
Q3: Ed25519 Key의 개인 키는 어떻게 보관하나요?
한 번 생성해 사용 후 삭제합니다. Biabahub 권장 절차는 로컬 OpenSSL로 키 쌍을 생성 → 공개 키를 Binance에 업로드 → 개인 키를 즉시 KMS(AWS KMS / GCP KMS 등)에 가져오기 → 로컬 물리 파기입니다. 전략 프로세스는 KMS에서 개인 키를 가져와 메모리에 캐시하며, 프로세스 재시작 시 다시 가져옵니다.
Q4: API가 계속 -1021 타임스탬프 오류를 반환하면 어떻게 하나요?
대개 서버의 NTP가 꺼져 있거나 드리프트가 큰 경우입니다. sudo timedatectl set-ntp true(Linux) 또는 w32tm /resync(Windows)로 강제 동기화하세요. 동기화 후에도 오류가 나면 GET /api/v3/time으로 Binance 서버 시간과 로컬 차이가 recvWindow 미만인지 확인합니다.
Q5: 하나의 Key로 현물과 선물을 동시에 실행할 수 있나요?
기술적으로 가능하며, Binance 권한에서 현물 / 선물은 두 개의 독립 스위치입니다. 그러나 Biabahub는 분리를 강력히 권장합니다. 현물 지정가와 선물 강제 청산의 위험 규모는 완전히 다르며, 하나의 Key를 공유한다는 것은 한 전략의 버그가 다른 전략에 영향을 줄 수 있음을 의미합니다.
Q6: API Key가 만료되면 알림 없이 만료되나요?
만료 7일 전 공식 이메일 알림이 발송되며, Biabahub는 자체 전략에도 만료 카운트다운 경보를 추가해 단일 채널에 의존하지 않을 것을 권장합니다.
Q7: 이전 Key 폐기 후 과거 주문은 여전히 조회 가능한가요?
가능합니다. 주문 기록은 Key와 분리되어 있으며, Key 폐기는 서명 채널을 닫는 것일 뿐 과거 주문은 계정 명세에 남아 웹에서 CSV로 내보낼 수 있습니다.
위험 안내
본 글은 Biabahub 팀이 정리한 API Key와 IP 화이트리스트 구성에 관한 기술 교육이며, 투자 자문, 법률 자문, 특정 전략의 손익 약속을 구성하지 않습니다. 프로그램 매매는 레버리지, 청산, 슬리피지, 네트워크 지연, 거래소 장애 등 다중 위험을 포함하며, 본 글의 예시 코드는 교육 시연용으로 실전 사용 전 반드시 완전한 백테스트, 페이퍼 트레이딩, 소액 실전의 3단계 검증을 거쳐야 하며 사용자가 모든 전략 결과에 대해 책임을 집니다. API Key가 유출되면 즉시 폐기해야 하며, 「고객 지원에게 보내 문제 해결을 돕겠다」는 요청은 모두 사기이며 Binance 공식은 Secret / Passphrase / 개인 키를 요구하지 않습니다. IP 화이트리스트도 만능은 아니며, 서버가 침해되면 공격자는 합법 IP 내에서 Key를 직접 사용할 수 있으므로 서버 자체에도 최소 권한, 정기 패치, 로그 감사 등 기본 보안 작업을 수행해야 합니다. 90일 순환은 하한이며 목표가 아닙니다. 고가치 계정은 30일 순환 또는 이벤트 기반 순환을 권장합니다. 공식 등록이 필요하면 Binance 공식 사이트를, 공식 App 다운로드는 Binance 공식 앱을 이용하세요.
문서 발행일 2026-07-01, 다음 재검토 예정 2026-10-01