바이낸스 API Key 생성은 다음 6단계로 이루어집니다. 바이낸스 공식 웹사이트에 로그인하고(API 기능은 웹에서만 가능하며 앱에서는 생성 불가), "계정 - API 관리"로 들어갑니다. "API 생성"을 클릭하고 "시스템 생성"을 선택한 후, 사용자 지정 레이블 이름을 입력하고 이메일+2FA+SMS의 3중 인증을 거칩니다. 시스템이 API Key와 Secret Key를 일회성으로 표시해 주면 즉시 복사하여 저장합니다(Secret Key는 한 번만 표시됩니다!). 마지막으로 권한(현물 거래/선물 거래/출금/읽기 등)과 IP 화이트리스트를 구성합니다. 강력히 권장: 생성된 모든 API Key는 반드시 IP 화이트리스트를 바인딩해야 합니다. IP 화이트리스트가 없는 API Key가 유출되면 자산을 통째로 넘겨주는 것과 같습니다. 바이낸스의 2024년 통계에 따르면, API Key 도난으로 인한 자금 손실의 93%가 IP 화이트리스트에 바인딩되지 않은 Key에서 발생했습니다. IP 화이트리스트를 바인딩하면 Secret Key가 유출되더라도 공격자가 자신의 서버에서 API를 호출할 수 없습니다. 바이낸스 공식 앱에서는 API Key를 생성할 수 없지만 기존 Key를 확인하고 삭제할 수 있어 응급 조치에 유용합니다. 아직 앱을 설치하지 않았다면 iOS 설치 튜토리얼을 참조하세요. 본 문서는 API Key의 생성, 권한 구성, 화이트리스트, 사용, 모니터링, 유출 시 응급 대처에 이르는 전체 수명 주기를 다룹니다.
API Key란 무엇인가요? 무엇을 할 수 있나요?
API Key(애플리케이션 프로그래밍 인터페이스 키)는 외부 프로그램이 귀하를 대신하여 바이낸스 계정을 조작할 수 있도록 하는 자격 증명입니다. API Key가 있으면 프로그램이 매번 로그인 비밀번호를 입력할 필요 없이 24시간 내내 계정 데이터를 읽고, 주문을 넣고, 내역을 조회할 수 있습니다.
전형적인 사용 시나리오는 5가지입니다: 퀀트 거래(예: Python 전략을 실행하여 자동 매매), 카피 트레이딩(프로그램이 유명 트레이더의 포지션을 복사하도록 함), 시장 데이터 획득(백테스트를 위해 과거 K-line 데이터를 일괄 수집), 자산 인벤토리(다중 계정의 총 자산을 자동 통계), 회계 기장(기업 재무 시스템과 연동).
API Key는 두 부분으로 구성됩니다: 신원을 식별하는 데 사용되며 공개되어도 무방한 API Key(공개 키), 요청 서명에 사용되며 절대 기밀을 유지해야 하는 Secret Key(개인 키). 은행 카드에 비유하자면 API Key는 카드 번호, Secret Key는 비밀번호와 같습니다. 카드 번호는 남에게 보여줘도 상관없지만 비밀번호가 유출되면 파국입니다.
API Key 생성 상세 단계
1단계: API 관리 페이지 진입. 바이낸스 공식 웹사이트에 로그인한 후(모바일 브라우저도 가능하나 앱 내 생성은 지원하지 않음), 우측 상단의 프로필 아이콘을 클릭하고 "API 관리(API Management)"를 선택합니다. 페이지 상단에는 생성된 모든 API Key 목록이, 하단에는 "API 생성" 버튼이 있습니다.
2단계: 생성 방식 선택. 바이낸스는 두 가지 방식을 제공합니다: "시스템 생성(System-generated)"은 대부분의 사용자에게 적합하며 키가 바이낸스에 의해 무작위로 생성됩니다. "자체 생성(Self-generated)"은 RSA/Ed25519 키 쌍을 가진 고급 사용자에게 적합하며, 사용자가 공개키/개인키를 직접 생성하고 공개키를 바이낸스에 업로드하여 더 높은 보안을 제공합니다(바이낸스는 귀하의 개인키를 알 수 없음).
일반 사용자는 "시스템 생성"을 선택하는 것으로 충분히 안전합니다. 기업 사용자나 전문 퀀트 팀은 "자체 생성" Ed25519 키 쌍을 사용하는 것이 좋습니다. 바이낸스는 2024년 5월부터 이 방식을 권장하고 있으며 서명 성능이 HMAC-SHA256보다 10배 이상 빠릅니다.
3단계: API Key 이름 지정. "현물 그리드 전략", "선물 마켓 메이킹", "잔액 모니터링"과 같이 의미 있는 레이블 이름을 입력합니다. 이 레이블은 자신에게만 보이며 나중에 용도를 구분하는 데 유용합니다. 한 전략당 하나의 Key를 사용하는 것이 좋으며, 하나의 Key를 여러 용도로 혼용하지 마세요.
4단계: 신원 인증. 이메일 6자리 인증 코드, SMS 6자리 인증 코드, Google OTP 6자리 동적 코드를 입력합니다. 3중 인증을 모두 통과해야 다음 단계로 넘어갈 수 있습니다.
5단계: Secret Key 저장. 인증을 통과하면 페이지에 API Key와 Secret Key가 표시됩니다. Secret Key는 이 순간 단 한 번만 표시되며 페이지를 닫으면 다시는 볼 수 없습니다. 즉시 복사하여 안전한 곳에 저장해야 합니다. 권장 사항:
- 비밀번호 관리자(1Password, Bitwarden)의 "암호화된 메모" 필드
- 로컬 암호화 파일(GPG로 암호화하여 USB 드라이브에 저장)
- 가장 안전함: 종이에 적어 금고에 보관(거액 계정에 적합)
절대 금물: 카카오톡/위챗 즐겨찾기, 이메일 임시 보관함, 일반 txt 파일, 암호화되지 않은 클라우드 드라이브 - 이러한 곳은 유출되기 쉽습니다.
6단계: 권한 및 IP 구성 (아래 상세 설명).
4단계 권한 시스템
바이낸스 API 권한은 "최소 권한" 원칙에 따라 낮은 것부터 높은 것까지 4단계로 나뉩니다. 전략에 꼭 필요한 권한만 활성화하세요.
Level 1: 읽기 전용 (Read Only). 계정 잔액, 주문 내역, 현재 포지션을 조회할 수 있지만 주문, 출금 또는 설정 변경은 할 수 없습니다. 이는 가장 안전한 수준으로 자산 모니터링, 재무 대사 및 세금 신고에 적합합니다.
Level 2: 현물 및 마진 거래 (Spot & Margin Trading). Level 1을 기반으로 주문 기능이 추가되어 현물과 마진을 매매할 수 있습니다. 선물 거래나 출금은 할 수 없습니다. 현물 퀀트 전략에 적합합니다.
Level 3: 선물 거래 (Futures Trading). 독립적인 스위치로 USDS-M 선물, COIN-M 선물, 옵션 거래 권限을 활성화할 수 있습니다. 선물은 레버리지가 있어 위험이 높으므로 충분한 백테스트를 거친 전략에만 이 권한을 부여하는 것이 좋습니다.
Level 4: 출금 활성화 (Enable Withdrawals). 가장 위험한 레벨입니다. 활성화하면 프로그램이 귀하 계정의 자산을 출금할 수 있습니다! 99%의 사용자는 이 권한을 활성화할 필요가 없습니다. 출금은 항상 수동으로 처리해야 합니다. 거래소 간 차익 거래나 자동 자산 통합과 같은 극소수의 시나리오에서만 필요하며, 이 경우 출금 주소 화이트리스트를 엄격하게 제한해야 합니다.
권한이 높을수록 공격 범위가 커집니다. 권장 원칙: 읽기, 현물, 선물은 필요에 따라 켜고 출금은 절대 켜지 마세요. 어느 날 전략에서 "출금 권한이 필요"하다는 것을 발견하면 출금 대신 내부 이체(예: USDS-M 선물에서 현물로)를 사용할 수 없는지 먼저 생각해보세요. 대부분의 시나리오에서 가능합니다.
IP 화이트리스트는 생명선입니다
이것이 본 문서의 가장 중요한 부분입니다. IP 화이트리스트가 없는 API Key 유출은 곧 계정 도난입니다.
IP 화이트리스트의 원리: 전략을 실행하는 서버의 IP 주소(예: AWS EC2 퍼블릭 IP: 47.98.xx.xx)를 화이트리스트에 추가하면 바이낸스 API 서버는 이 IP에서 오는 요청만 수락합니다. 다른 IP에서 요청하면 Secret Key 서명이 맞더라도 거부됩니다.
생성 시 IP 구성 옵션:
- 신뢰할 수 있는 IP만 접근 제한(권장): 한 줄에 하나씩 1~20개의 IP 주소를 입력합니다. "47.98.123.45"와 같은 IPv4 형식이 지원되며 대역(예: 192.168.1.0/24)은 지원되지 않습니다.
- 제한 없음(절대 권장하지 않음): 어떤 IP든 이 Key를 사용할 수 있습니다. 바이낸스는 2024년부터 "IP 제한 없음" Key의 유효 기간을 90일로 제한했습니다. 만료되면 자동으로 무효화되어 다시 생성해야 하므로 사용자가 IP 화이트리스트를 사용하도록 강제하고 있습니다.
서버 IP 확인 방법: SSH로 서버에 로그인한 후 curl ifconfig.me 또는 curl ip.sb를 실행하면 퍼블릭 IP가 반환됩니다. 가정용 브로드밴드 사용자는 주의하세요. 가정용 IP는 대부분 동적이므로 연결될 때마다 변경될 수 있어 API 화이트리스트에 적합하지 않습니다. VPS(고정 IP) 또는 클라우드 함수 서비스를 사용하는 것이 좋습니다.
교차 지역 배포: 전략이 여러 서버(주/예비 또는 다중 지역)에서 실행되는 경우 모든 IP를 화이트리스트에 추가하세요. 바이낸스는 최대 20개의 IP를 허용합니다.
임시 디버깅: 개발 단계에서 로컬 컴퓨터에서 전략을 테스트하려는 경우 가정의 퍼블릭 IP를 임시로 화이트리스트에 추가하고, 테스트가 완료되면 즉시 제거하여 서버 IP만 남길 수 있습니다.
API 사용 시 보안 실천 사항
실천 1: Secret Key를 코드에 하드 코딩하지 마세요. .py, .js 파일에 직접 적지 마세요. Git 저장소(특히 공개 리포지토리)에 커밋되는 것을 방지하기 위함입니다. 올바른 방법은 환경 변수(export BINANCE_SECRET=xxx) 또는 구성 파일(.env, .gitignore에 추가)을 사용하는 것입니다.
실천 2: 독립적인 하위 계정으로 위험 격리. 바이낸스에서는 최대 200개의 하위 계정을 무료로 만들 수 있습니다. 각 전략을 독립된 하위 계정에서 실행하고 메인 계정에는 이체용 소액의 자금만 남겨두는 것이 좋습니다. 하위 계정의 API Key가 도난당하더라도 손실은 하위 계정의 잔액에 국한됩니다.
실천 3: 권한 분리 사용. 잔액 확인용으로는 Read Only Key를, 거래용으로는 Spot Trading Key를 사용하세요. 프런트엔드 표시 및 리포트 작성용 읽기 Key는 IP 제한 없이 둘 수 있지만, 거래용 Key는 IP를 엄격하게 바인딩하고 권한을 설정해야 합니다.
실천 4: 정기적 순환. 90일마다 API Key를 새로 생성하고 예전 것은 삭제하세요. 이전 Key가 장기간 감시당했더라도 90일 후면 무효화됩니다. 바이낸스 API 관리 페이지에는 각 Key의 생성 시간이 표시되어 추적하기 편리합니다.
실천 5: 비정상적 호출 모니터링. 바이낸스는 API Key 호출 통계를 제공합니다. "API 관리" 페이지에서 Key 우측의 "세부 정보 보기"를 클릭하면 분당 호출 횟수, 최대 가중치 소모량, 속도 제한(Rate Limit) 초과 횟수를 확인할 수 있습니다. 특정 Key의 호출량이 갑자기 두 배로 늘어났다면 누군가 남용하고 있을 수 있습니다.
API Key가 유출되었을 때는 어떻게 하나요?
1단계: 앱 또는 웹에서 즉시 해당 API Key를 삭제합니다. API 관리 페이지로 들어가 유출된 Key 우측의 "삭제" 버튼을 클릭하고 확인하면 Key가 즉시 무효화됩니다. 삭제는 되돌릴 수 없으니 망설이지 마세요.
2단계: 계정 조작 기록 확인. 지난 24시간 동안의 거래, 출금, 입금 기록을 확인하여 비정상적인 거래가 있는지 파악합니다. 만약 공격자가 Key를 이용해 인지도 없는 잡코인을 매수했다면(전형적인 펌프 앤 덤프 공격) 즉시 고객 지원 센터에 연락하여 계정을 동결하세요.
3단계: 기타 관련 보안 설정 초기화. 로그인 비밀번호를 변경하고 2FA를 초기화하며 다른 API Key는 안전한지 확인합니다. 공격자가 계정의 다른 자격 증명도 동시에 탈취했을 가능성이 있기 때문입니다.
4단계: 유출 경로 추적. 흔한 유출 경로로는 공개 Git 리포지토리에 코드가 푸시된 경우(github.com/searchcode 등의 도구로 자신의 Secret Key 검색), 서버 침해(auth.log 확인), 스크린샷에 실수로 찍힌 경우, "고객 센터"에 키를 제공한 경우(사기), 악성 오픈소스 퀀트 프레임워크를 사용한 경우 등이 있습니다. 근본 원인을 찾아야 다시 유출되는 것을 막을 수 있습니다.
5단계: 티켓 제출. 자금 손실이 없더라도 바이낸스 고객 지원 센터에 티켓을 제출하여 상황을 설명하고 "API 유출 냉각기(API Leak Cooling-Off Period)"를 활성화해 달라고 요청하는 것이 좋습니다. 계정이 7일 동안 강화된 출금 심사 상태에 들어가며 모든 출금에 대해 수동 심사가 진행됩니다.
자주 발생하는 에러 코드 및 처리 방법
| 에러 코드 | 의미 | 처리 방법 |
|---|---|---|
| -1021 | 타임스탬프가 서버 시간 창(Time Window)을 벗어남 | NTP를 통해 서버 시간을 동기화하세요 |
| -1022 | 서명 무효 | Secret Key 및 파라미터 결합 순서를 확인하세요 |
| -2010 | 주문 실패: 잔액 부족 | 사용 가능한 잔액 및 동결 자산을 확인하세요 |
| -2014 | API Key 형식 오류 | Key 문자열이 누락되지 않았는지 확인하세요 |
| -2015 | API Key 무효/비활성화됨/IP 화이트리스트 불일치 | IP 화이트리스트를 중점적으로 확인하세요 |
| -1003 | 요청이 너무 빈번함 | 호출 빈도를 낮추고 가중치(Weight)를 주의하세요 |
| -4131 | 선물 API 권한이 활성화되지 않음 | API 관리 페이지에서 선물 권한을 활성화하세요 |
-2015 오류가 발생하는 가장 흔한 이유는 IP 화이트리스트 구성이 잘못되었거나 서버 IP가 변경되었기 때문입니다. curl ifconfig.me를 사용하여 현재 IP를 다시 확인하고 화이트리스트와 대조해보세요.
자주 묻는 질문 (FAQ)
Q: API Key는 몇 개까지 만들 수 있나요? A: 현재 단일 계정당 최대 30개의 API Key로 제한되어 있습니다. 이는 대부분의 사용자에게 충분합니다.
Q: Secret Key를 분실하면 어떻게 하나요? A: 새 API Key를 다시 생성하는 수밖에 없습니다. 예전 Key + Secret 조합은 영원히 찾을 수 없습니다. 생성 시 즉시 Secret Key를 저장해야 하는 이유가 바로 이것입니다.
Q: API Key 사용 요금이 있나요? A: 무료입니다. 거래 수수료는 수동 거래와 동일하며 API 사용에 대한 추가 비용은 없습니다.
Q: API Key에 유효 기간이 있나요? A: 영구적으로 유효합니다(단, IP 화이트리스트가 없는 키는 2024년부터 90일로 제한됨). 하지만 보안을 높이기 위해 90일마다 직접 교체(로테이션)하는 것을 권장합니다.
Q: 문제 해결을 돕기 위해 고객 지원 센터에 API Key를 보내도 되나요? A: 절대 안 됩니다! 진짜 고객 센터는 절대 귀하에게 Secret Key를 요구하지 않습니다. Secret Key를 요구하는 사람은 모두 사기꾼입니다.