Binance API 서명 생성 및 검증 완벽 가이드

저는 글로벌 결제 시스템을 개발하면서 Binance API와 연동해야 하는 상황에 직면한 경험이 있습니다. 초당 수천 건의 거래 요청을 처리해야 하는 환경에서, API 서명 검증机制的 정확한 이해가 시스템 보안과 성능을 좌우했습니다. 이 튜토리얼에서는 Binance API 서명의 원리부터 실제 구현, 그리고 자주 발생하는 문제 해결까지 폭넓게 다룹니다.

Binance API 서명이 필요한 이유

Binance API는 HMAC SHA256 서명 방식을 사용하여 요청자의 정합성을 검증합니다. 이 메커니즘은 API 키와 시크릿 키의 조합으로 생성되며, 다음 세 가지 보호 기능을 제공합니다:

• 인증(Authentication): 요청자가 유효한 API 키를 보유했는지 확인
• 무결성(Integrity): 요청 데이터가 전송 과정에서 변조되지 않았음을 보장
• 반복 공격 방지(Replay Protection): 타임스탬프를 통한 유효기간 제한

서명 생성 원리

Binance API 서명은 다음 수식으로 생성됩니다:

signature = HMAC-SHA256(secretKey, queryString)
queryString = "param1=value1¶m2=value2×tamp=1234567890"

서명할 때 반드시 다음 매개변수를 포함해야 합니다:

• timestamp: Unix 밀리초 타임스탬프 (필수)
• recvWindow: 요청 유효 기간 (선택, 기본값 5000ms)
• 서명 대상이 아닌 헤더: X-MBX-APIKEY

Python으로 Binance API 서명 생성하기

저는 Python 개발 환경에서 Binance API 서명을 구현할 때 다음 패턴을 사용합니다. 이 코드는 실제 프로덕션 환경에서 검증된 것입니다.

import hmac
import hashlib
import time
import requests
from urllib.parse import urlencode

class BinanceAPIClient:
    def __init__(self, api_key: str, api_secret: str, base_url: str = "https://api.binance.com"):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = base_url
    
    def _generate_signature(self, query_string: str) -> str:
        """HMAC-SHA256 서명 생성"""
        signature = hmac.new(
            self.api_secret.encode('utf-8'),
            query_string.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()
        return signature
    
    def _create_signed_request(self, endpoint: str, params: dict) -> dict:
        """서명된 요청 생성"""
        # 타임스탬프 추가
        params['timestamp'] = int(time.time() * 1000)
        params['recvWindow'] = 5000
        
        # 쿼리 문자열 생성 (URL 인코딩)
        query_string = urlencode(params, safe='')
        
        # 서명 생성
        signature = self._generate_signature(query_string)
        
        # 요청 헤더
        headers = {
            'X-MBX-APIKEY': self.api_key,
            'Content-Type': 'application/x-www-form-urlencoded'
        }
        
        return {
            'url': f"{self.base_url}{endpoint}",
            'params': f"{query_string}&signature={signature}",
            'headers': headers
        }
    
    def get_account_info(self) -> dict:
        """계정 정보 조회 (서명 필요)"""
        request = self._create_signed_request('/api/v3/account', {})
        
        response = requests.get(
            request['url'],
            params=request['params'],
            headers=request['headers']
        )
        
        return response.json()

사용 예시
client = BinanceAPIClient(
    api_key='YOUR_API_KEY',
    api_secret='YOUR_API_SECRET'
)

계정 정보 조회
account_info = client.get_account_info()
print(account_info)

Node.js로 Binance API 서명 생성하기

Node.js 환경에서는 crypto 모듈을 활용하여 동일한 서명 로직을 구현합니다. 다음 코드는 AWS Lambda에서 주기적으로 포지션을 모니터링하는 데 사용되었습니다.

const crypto = require('crypto');
const axios = require('axios');

class BinanceAPIClient {
    constructor(apiKey, apiSecret, baseUrl = 'https://api.binance.com') {
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
        this.baseUrl = baseUrl;
    }

    /**
     * HMAC-SHA256 서명 생성
     * @param {string} queryString - 서명할 쿼리 문자열
     * @returns {string} hex 인코딩된 서명
     */
    generateSignature(queryString) {
        return crypto
            .createHmac('sha256', this.apiSecret)
            .update(queryString)
            .digest('hex');
    }

    /**
     * 서명된 API 요청 실행
     * @param {string} method - HTTP 메서드 (GET, POST, DELETE)
     * @param {string} endpoint - API 엔드포인트
     * @param {object} params - 요청 매개변수
     * @returns {Promise