바이낸스 API 키는 어떻게 관리하나요? 최소 권한 설정과 정기 점검
바이낸스 API 키는 기본적으로 읽기 권한만 있으며, 현물 거래, 선물 거래, 출금을 활성화하려면 별도로 체크해야 합니다. 모범 사례는 용도별로 여러 키를 나누고 + IP 화이트리스트를 걸고 + 90일마다 교체하는 것입니다. 이번에 API 키 5개를 설정한 실측 과정과 겪었던 시행착오를 기록합니다.
바이낸스 API 키는 프로그램 거래, 시세 구독, 서드파티 전략 플랫폼에 사용하는 접근 토큰입니다. 바이낸스 공식 사이트에 로그인해 [API 관리]에서 키를 생성하면 기본적으로 [읽기 권한]만 부여되며, [현물 거래], [선물 거래], [출금]은 각각 별도로 체크해야 활성화됩니다. 이번에는 용도별로 5개의 독립 키를 만들어 각각 최소 권한 + IP 바인딩을 적용해, 단일 키가 유출되더라도 최대 손실 범위를 그 키의 권한 범위 안으로 제한했습니다.
가장 중요한 원칙은 프로그램이 정말로 자동 출금이 필요한 경우가 아니라면 API 키에 절대 출금 권한을 부여하지 마세요입니다. 99%의 프로그램은 출금 기능이 필요 없지만, 활성화한 상태에서 키가 유출되면 자산이 바로 빠져나갑니다. 활성화하더라도 반드시 화이트리스트와 함께 설정해야 합니다(바이낸스 출금 화이트리스트는 어떻게 설정하나요? 추가와 대기 기간 상세 참고).
5가지 권한 항목이 각각 무엇을 하는가
아래 표는 바이낸스 API 키의 모든 권한 옵션과 추천 체크 전략입니다.
| 권한 | 기능 | 위험도 | 추천 |
|---|---|---|---|
| Enable Reading(읽기 권한) | 시세, 잔액, 주문 조회 | 매우 낮음 | 필수 체크 |
| Enable Spot & Margin Trading(현물+마진 거래) | 주문, 취소 | 중(최대 손실은 잘못된 매매 정도) | 필요에 따라 |
| Enable Futures(선물 거래) | 선물 주문, 레버리지 조정 | 중상(레버리지로 손실 확대) | 필요에 따라 |
| Enable Withdrawals(출금) | 지정 주소로 온체인 출금 | 매우 높음(자산이 바로 빠져나감) | 거의 체크하지 않음 |
| Permits Universal Transfer(계정 간 이체) | 현물/선물/펀딩 계정 간 이체 | 낮음 | 필요에 따라 |
읽기 권한은 기본으로 부여되어 별도 체크가 필요 없습니다. 현물과 선물 권한은 프로그램 용도에 따라 체크하세요. 출금 권한은 부득이한 경우에만 체크하고, 체크한 후에는 반드시 출금 주소를 바인딩해야 합니다(이 단계는 API 키 설정이 아니라 화이트리스트에서 진행합니다).
1단계: API 키 생성
[API 관리] 진입점은 [계정 센터] → [API 관리]이며 앱도 같은 경로입니다. [API 생성]을 눌러 [System generated] 또는 [Self-generated]를 선택합니다.
| 유형 | 차이 | 추천 상황 |
|---|---|---|
| System generated(시스템 생성) | 바이낸스가 시크릿을 생성하며 본인은 한 번만 볼 수 있음 | 99%의 상황 |
| Self-generated(자체 생성) | Ed25519/RSA 공개키 사용, 시크릿이 서버에 업로드되지 않음 | 고보안 상황 |
일반 사용자는 [System generated]로 충분합니다. 키에 이름을 붙이고(30자 이내, 예: bot-spot-grid-arb) [생성]을 누르세요. 시스템이 2FA 코드 + 이메일 인증번호 + SMS 인증번호(등록된 경우)를 요구하며 세 가지 모두 통과해야 생성됩니다.
생성이 완료되면 API 키(공개키, 64자리)와 Secret 키(개인키, 64자리)가 표시됩니다. Secret 키는 이번 한 번만 표시되며 페이지를 닫으면 다시 볼 수 없습니다. 즉시 Secret을 복사해 비밀번호 관리자나 암호화된 메모에 저장하세요. 분실하면 키를 삭제하고 새로 만드는 수밖에 없습니다.
2단계: 권한 체크
새로 만든 키는 기본적으로 읽기 권한만 있습니다. 거래 권한을 활성화하려면 [Edit restrictions]를 눌러 해당 권한을 체크하고 2FA 코드로 확인하면 됩니다. 권한을 변경할 때마다 2FA + 이메일 인증이 트리거됩니다.
이번에 설정한 5개 키 구성은 다음과 같습니다.
| 키 이름 | 용도 | 권한 | IP 제한 |
|---|---|---|---|
bot-spot-grid |
현물 그리드 봇 | 읽기 + 현물 거래 | IP 1개로 제한 |
bot-futures-trend |
선물 추세 전략 | 읽기 + 선물 거래 | IP 1개로 제한 |
tax-export |
세금 신고 내보내기 도구 | 읽기 전용 | IP 2개로 제한 |
dashboard-only |
본인용 모니터링 대시보드 | 읽기 전용 | 제한 없음(집 와이파이에서만 사용) |
manual-transfer |
수동 계정 이체 도구 | 읽기 + 계정 이체 | IP 1개로 제한 |
5개 모두 출금 권한을 켜지 않았습니다. 언젠가 이 중 하나가 유출되더라도 최대 손실은 상대방에게 잘못 매매당하는 정도이고(그마저도 해당 키의 현물/선물 권한 범위 내), 코인 자체는 빠져나갈 수 없습니다.
3단계: IP 화이트리스트 바인딩 — 핵심 단계
[Edit restrictions] 페이지 하단에 [Restrict access to trusted IPs only]가 있습니다. 열어서 IP 주소를 입력하세요(여러 개는 쉼표로 구분, 최대 30개).
왜 반드시 IP를 바인딩해야 하는가:
- API 키와 Secret이 유출되더라도 도용자의 서버 IP는 화이트리스트에 없습니다
- 바이낸스 서버는 화이트리스트 외의 IP에서 오는 모든 요청을 거부하고 -2015 오류를 반환합니다
- '지리적 위치'라는 인증 계층을 하나 더 추가하는 효과입니다
IP를 바인딩하지 않았을 때의 대가:
- IP 제한이 없는 키는 90일 후 바이낸스가 강제로 자동 만료시킵니다(2024년부터 시행된 규칙입니다)
- IP를 바인딩한 키는 자동 만료되지 않고 장기간 사용할 수 있습니다
서버 IP를 찾는 방법:
- 자체 호스팅 봇: 해당 기기에서
curl ifconfig.me를 실행해 아웃바운드 IP 확인 - 클라우드 함수 또는 PaaS: 서비스 제공사가 제공하는 고정 아웃바운드 IP 확인(많은 PaaS는 아웃바운드 IP가 고정되지 않아 별도로 NAT를 설정해야 함)
- 집에서 운영: 가정용 회선의 공인 IP(매일 바뀌는 동적 IP는 관리가 번거로워 가정용 바인딩은 권장하지 않음)
프로그램이 동적 IP 환경(예: 가정용 회선, 재택근무)에 배포되어 있다면, IP를 바인딩하지 않으면 90일 후 강제 만료되고, 바인딩하면 IP 변동 시마다 실패합니다. 이런 경우 VPS(고정 IP)로 옮기거나 내부망 터널링 방식을 사용해야 합니다.
이번에 5개 키 중 4개는 IP를 바인딩했고, 나머지 [dashboard-only]는 읽기 전용이라 권한 자체가 낮아 바인딩하지 않아도 안전합니다.
4단계: 키가 정상 작동하는지 테스트
생성이 끝나면 curl로 테스트합니다.
curl -H "X-MBX-APIKEY: 본인의 API 키" \
https://api.binance.com/api/v3/account?timestamp=1234567890&signature=xxx
계정 정보가 반환되면 키가 정상 작동하는 것입니다. 다음이 반환되면:
| 오류 코드 | 의미 | 처리 방법 |
|---|---|---|
| -2014 | API 키 무효 | 키를 온전히 복사했는지, 공백이 있는지 확인 |
| -2015 | IP가 화이트리스트에 없음 | 현재 아웃바운드 IP를 확인해 화이트리스트에 추가 |
| -1022 | 서명 오류 | Secret 키와 서명 알고리즘 확인 |
| -1021 | 타임스탬프 범위 초과 | 서버 시간이 맞지 않으니 시간 동기화 |
| -2010 | 해당 권한 없음 | 해당 키에 권한이 체크되지 않았으니 [Edit]에서 추가 |
| -4007 | 출금 주소가 화이트리스트에 없음 | 출금 API에서만 발생, 화이트리스트에 추가 |
가장 많이 겪는 오류는 -2015 IP가 화이트리스트에 없는 경우입니다. VPN, Cloudflare, 특정 회사 네트워크를 사용하면 본인의 진짜 아웃바운드 IP를 모르는 경우가 많기 때문입니다. 바이낸스 공식 앱의 [API 관리]에서도 [최근 접속 IP]를 확인할 수 있으니, 본인이 예상한 IP와 일치하는지 비교해 보세요.
5단계: 정기 점검 + 교체
90일마다 API 키 점검을 진행하세요.
1. 모든 키 나열: [API 관리] 메인 페이지에서 전체 키 목록을 볼 수 있으며, 각 키의 생성 시간, 최근 접속 시간, 권한, IP 제한이 한눈에 표시됩니다.
2. 의심스러운 키 찾기:
- 어느 프로그램용인지 이미 모르는 키 → 삭제
- 30일간 [최근 접속] 기록이 없는 키 → 삭제
- IP가 바인딩되지 않은 키 → IP 추가 또는 삭제
- 실제 필요보다 권한이 과한 키 → 최소 권한으로 수정
3. 능동 교체: 큰 자산을 다루는 중요한 키는 90일마다 능동적으로 재생성하는 것을 권장합니다. 기존 키 삭제 → 새 키 생성 → 프로그램에 업데이트 → 정상 작동 확인 → 완료 순서입니다. 이 과정에서 프로그램이 1~5분 정도 잠시 중단될 수 있으니 활동이 적은 시간대에 진행하세요.
4. 삭제 전 확인 사항: API 키 삭제는 즉시 적용되며 되돌릴 수 없습니다. 삭제 전 다음을 확인하세요.
- 이 키가 실행 중인 어떤 프로그램에서도 참조되지 않는지
- 이 키가 어떤 cron job이나 예약 작업에도 남아 있지 않은지
- Git 저장소의
.env, 설정 파일에 남아 있지 않은지(이미.gitignore에 있어야 하지만 다시 한번 확인)
API 키 유출 시 긴급 대응
키가 유출됐을 가능성이 있다면(예: 실수로 공개 Git 저장소에 push한 경우) 즉시 다음을 하세요.
- 1초 안에: [API 관리]에서 해당 키를 삭제
- 2초 안에: 해당 키의 최근 24시간 거래 내역을 확인해 의심스러운 주문이 있는지 점검
- 3초 안에: 출금 권한이 켜져 있었다면 의심스러운 출금이 있는지 확인(화이트리스트에서 차단됐어야 하지만 그래도 확인)
- 4초 안에: 계정 비밀번호 변경 + 2FA 재설정(다른 자격 증명도 유출됐을 증거가 없더라도 전부 한 번씩 교체)
- 이후: Git 저장소에 이미 push됐다면 키만 삭제하는 걸로는 부족합니다.
git filter-branch나 BFG 도구로 Git 히스토리 속 시크릿도 삭제해야 합니다. 그렇지 않으면 커밋 히스토리에서 누군가 다시 찾아낼 수 있습니다
GitHub와 GitLab 모두 시크릿 자동 스캔 서비스를 제공하며, 바이낸스 API Secret이 공개 저장소에 push되면 바이낸스가 몇 시간 안에 플랫폼 알림을 받아 능동적으로 해당 키를 무효화합니다. 하지만 이건 어디까지나 최후의 안전망일 뿐, 이것만 믿어서는 안 됩니다.
서드파티 플랫폼에서 API 키를 쓸 때의 함정
많은 서드파티 전략 플랫폼, 세금 신고 도구, 포트폴리오 관리 도구가 API 키를 입력하라고 요구합니다. 원칙은 다음과 같습니다.
| 서드파티 유형 | 부여해야 할 권한 | 위험 신호 |
|---|---|---|
| 세금 신고 내보내기 도구 | 읽기 전용 | 출금 권한을 요구 → 바로 피하세요 |
| 포트폴리오 모니터링 대시보드 | 읽기 전용 | 거래 권한을 요구 → 신중히 검토 |
| 카피트레이딩 / 시그널 / 전략 플랫폼 | 읽기 + 현물/선물 거래 | 출금 권한을 요구 → 절대 피하세요 |
| 레버리지 대납 / 대출 도구 | 아예 사용하지 마세요, 피하세요 | 출금을 요구하는 것은 모두 피하세요 |
레드라인: 서드파티 도구가 당당하게 출금 권한을 요구한다면 99%는 먹튀를 노리는 것입니다. 세금 신고, 모니터링, 카피트레이딩 모두 출금 권한이 필요 없으며 읽기, 많아야 거래 권한만 필요합니다.
이번에 저희는 선물 카피트레이딩 플랫폼 한 곳에 [읽기 + 선물 거래] 권한을 부여했는데, 그쪽이 [출금] 권한을 요구했을 때 거절했고 상대방도 수용했습니다. 이는 이 권한이 애초에 선택 사항이었다는 뜻이며, 그들이 반드시 필요했다면 떠났을 것입니다.
자주 묻는 질문
Q: API 키와 Secret 키 중 어느 쪽이 더 민감한가요? A: Secret 키가 더 민감합니다. API 키는 사용자 식별용이라 타인에게 알려줘도 되지만, Secret 키는 서명용 키라 유출되면 모든 권한이 도용됩니다. Secret은 어떤 이메일, 채팅, 이슈에도 절대 적어서는 안 됩니다.
Q: API 키와 Secret은 어떻게 안전하게 보관하나요?
A: 로컬에서는 1Password / Bitwarden / KeePass 같은 비밀번호 관리자를 사용하고, 서버에서는 환경 변수 + Docker secrets나 K8s Secret을 사용하며 코드에 하드코딩하지 마세요. Git 저장소에는 반드시 .env가 .gitignore에 포함되어야 합니다.
Q: 바이낸스에서 API 키를 발급받은 후 이름을 바꿀 수 있나요? A: 바꿀 수 있습니다. [API 관리]에서 해당 키를 찾아 [Edit restrictions]에서 이름을 변경할 수 있습니다. 이름 변경은 키/Secret 자체에 영향을 주지 않으며 본인이 보기 위한 라벨일 뿐입니다.
Q: API 키의 개수 제한은 몇 개인가요? A: 단일 계정당 최대 30개까지 가능합니다. 보통 5~10개면 용도별로 충분히 나눌 수 있으며, 30개는 대량의 서브 계정이나 퀀트 팀을 위해 설계된 수치입니다.
Q: 서브 계정의 API와 메인 계정 API는 차이가 있나요? A: 차이가 있습니다. 서브 계정 API는 서브 계정 내 자산만 조작할 수 있고 메인 계정을 건드릴 수 없습니다. 서브 계정끼리도 서로 격리됩니다. 서브 계정은 전략 격리와 리스크 격리에 특히 적합해 퀀트 팀이 자주 사용합니다.
Q: API 키에 접근 빈도 제한이 있나요? A: 있습니다. 바이낸스의 모든 엔드포인트에는 weight(가중치) 제한이 있어 간단한 엔드포인트는 weight=1, 복잡한 엔드포인트는 weight=20입니다. 각 IP는 분당 1200 weight의 총 한도가 있으며 초과하면 -1003 제한 오류가 반환됩니다. 잔액 조회, 주문 조회는 가볍고 주문 자체도 가볍지만, 전체 캔들 조회나 전체 페어 조회는 빠르게 한도를 소진합니다.
Q: API 키를 삭제하면 과거 거래 내역도 사라지나요? A: 사라지지 않습니다. 거래 내역과 주문 이력은 계정 레벨에 속하며 특정 키와 무관합니다. 키를 삭제해도 접근 자격만 멈추고 계정 내 데이터는 전부 그대로 남습니다.
Q: 화이트리스트 IP는 IPv6를 지원하나요? A: 지원합니다. 바이낸스 API 화이트리스트는 IPv4와 IPv6 주소를 모두 지원하며 입력 형식도 일반적인 것과 동일합니다. 서버가 v4와 v6 아웃바운드를 모두 가지고 있다면 둘 다 추가하는 것을 권장합니다.
Q: API가 90일 후 자동 만료된다는 게 무슨 뜻인가요? A: IP 화이트리스트를 바인딩하지 않은 API 키는 생성일로부터 90일 후 바이낸스가 자동으로 만료시켜 재생성이 필요합니다. IP를 바인딩한 키는 자동 만료되지 않습니다. 바이낸스 공식 공지에 있는 규칙으로 2024년부터 시행됐으며, 장기간 관리되지 않는 키를 정리하기 위한 목적입니다.