바이낸스 현물(Spot) API 사용법: 첫 주문까지 가능한 실행 코드 가이드

바이낸스 현물(Spot) API를 시작하는 가장 빠른 방법은 다음과 같습니다: API Key와 Secret을 준비한 후, 먼저 /api/v3/ping을 호출하여 연결 상태를 확인하고, /api/v3/time으로 서버 시간을 동기화한 다음, /api/v3/account(서명 인터페이스)를 통해 잔액을 조회하여 권한을 확인하는 것입니다. 전체 과정은 약 10분 내외로 첫 주문까지 완료할 수 있습니다. 본문에서는 각 단계별 curl 및 Python 전체 코드를 제공하며, 모든 엔드포인트는 실제로 사용되는 https://api.binance.com 주소를 기반으로 합니다. 아직 API 키가 준비되지 않았다면 바이낸스 공식 사이트에서 KYC를 완료하시기 바라며, 계정이 없다면 무료 가입을 통해 계정을 생성하세요.

1. Spot API의 인터페이스 계층

바이낸스 현물 REST API는 인증 레벨에 따라 세 가지로 분류됩니다:

인증 인터페이스는 쿼리 파라미터 끝에 signature=<HMAC-SHA256 서명>을 붙여야 하며, 요청 헤더에 X-MBX-APIKEY를 포함해야 합니다.

2. 환경 준비 및 연결 테스트

1) 종속성 설치

# Python 3.8+
pip install requests python-dotenv

# 또는 공식 SDK 사용
pip install python-binance

2) 기본 URL 선택

바이낸스 현물 API는 5개의 미러 사이트를 제공합니다. 코드에서는 api.binance.com을 사용하고, 실패 시 api-gcp.binance.com으로 대체하는 것이 좋습니다.

ENDPOINTS = [
    "https://api.binance.com",      # 기본값
    "https://api-gcp.binance.com",  # Google Cloud 라인
    "https://api1.binance.com",
    "https://api2.binance.com",
    "https://api3.binance.com",
]

3) 첫 번째 요청: ping

curl -X GET "https://api.binance.com/api/v3/ping"
# {} 가 반환되면 정상 연결

4) 서버 시간 동기화

curl -X GET "https://api.binance.com/api/v3/time"
# {"serverTime":1713027384562}

로컬 시간과 serverTime의 차이가 1000ms를 초과하면 인증 인터페이스에서 -1021 오류가 발생하므로, 퀀트 서버는 반드시 NTP 설정을 켜야 합니다.

3. 계정 잔액 조회 (서명 인터페이스)

서명, 재시도, 타임스탬프 오프셋 처리를 포함한 실행 가능한 Python 래퍼 예제입니다:

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

API_KEY = "본인의_API_KEY"
SECRET_KEY = "본인의_SECRET_KEY"
BASE_URL = "https://api.binance.com"

def _sign(params: dict) -> dict:
    params["timestamp"] = int(time.time() * 1000)
    params["recvWindow"] = 5000
    query = urlencode(params)
    params["signature"] = hmac.new(
        SECRET_KEY.encode(),
        query.encode(),
        hashlib.sha256
    ).hexdigest()
    return params

def _request(method: str, path: str, params: dict = None, signed: bool = False):
    params = params or {}
    headers = {"X-MBX-APIKEY": API_KEY} if signed else {}
    if signed:
        params = _sign(params)
    url = f"{BASE_URL}{path}"
    r = requests.request(method, url, params=params, headers=headers, timeout=10)
    r.raise_for_status()
    return r.json()

def get_account():
    return _request("GET", "/api/v3/account", signed=True)

# 호출
balances = get_account()["balances"]
non_zero = [b for b in balances if float(b["free"]) > 0]
for b in non_zero:
    print(f"{b['asset']}: {b['free']} (잠김 {b['locked']})")

반환 구조 예시:

{
  "makerCommission": 10,
  "takerCommission": 10,
  "canTrade": true,
  "canWithdraw": true,
  "canDeposit": true,
  "accountType": "SPOT",
  "balances": [
    {"asset": "BTC", "free": "0.00123456", "locked": "0.00000000"},
    {"asset": "USDT", "free": "128.45", "locked": "0.00"}
  ]
}

4. 시세 및 K라인 조회 (공개 인터페이스)

시세 인터페이스는 서명이 필요 없지만, 가중치(Weight) 제한이 있습니다:

def get_price(symbol: str) -> float:
    r = _request("GET", "/api/v3/ticker/price", {"symbol": symbol})
    return float(r["price"])

def get_depth(symbol: str, limit: int = 20) -> dict:
    return _request("GET", "/api/v3/depth", {"symbol": symbol, "limit": limit})

def get_klines(symbol: str, interval: str = "1h", limit: int = 500):
    return _request("GET", "/api/v3/klines", {
        "symbol": symbol,
        "interval": interval,  # 1m, 5m, 15m, 1h, 4h, 1d
        "limit": limit
    })

print(get_price("BTCUSDT"))  # 68420.12

성능 팁: 단일 가격 조회는 /ticker/price(가중치 1), 전체 페어 조회는 /ticker/24hr(가중치 40)를 사용하는 것이 루프를 도는 것보다 가중치를 99% 절약할 수 있습니다.

5. 주문 및 취소 (TRADE 인터페이스)

현물 주문 엔드포인트는 POST /api/v3/order이며, 필수 파라미터는 type에 따라 달라집니다.

1) 지정가 주문 (LIMIT)

def place_limit_order(symbol: str, side: str, quantity: float, price: float):
    return _request("POST", "/api/v3/order", {
        "symbol": symbol,
        "side": side,              # BUY 또는 SELL
        "type": "LIMIT",
        "timeInForce": "GTC",      # GTC / IOC / FOK
        "quantity": quantity,
        "price": price,
    }, signed=True)

order = place_limit_order("BTCUSDT", "BUY", 0.001, 60000.00)
print(order["orderId"], order["status"])

2) 시장가 주문 (MARKET)

시장가 주문은 수량(quantity) 또는 금액(quoteOrderQty) 기준으로 넣을 수 있습니다:

# BTC 수량 기준으로 매수 (해당하는 USDT 소모)
_request("POST", "/api/v3/order", {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "MARKET",
    "quantity": 0.001
}, signed=True)

# USDT 금액 기준으로 매수 (더 자주 사용됨, 슬리피지 예방)
_request("POST", "/api/v3/order", {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "MARKET",
    "quoteOrderQty": 100  # 100 USDT로 BTC 매수
}, signed=True)

3) 주문 상태 조회

def get_order(symbol: str, order_id: int):
    return _request("GET", "/api/v3/order", {
        "symbol": symbol,
        "orderId": order_id
    }, signed=True)

status = get_order("BTCUSDT", 12345678)
# status["status"] 값: NEW / PARTIALLY_FILLED / FILLED / CANCELED / REJECTED

4) 주문 취소

def cancel_order(symbol: str, order_id: int):
    return _request("DELETE", "/api/v3/order", {
        "symbol": symbol,
        "orderId": order_id
    }, signed=True)

cancel_order("BTCUSDT", 12345678)

6. 테스트넷 먼저 활용하기 (자산 손실 방지)

바이낸스는 무료 테스트 코인을 제공하는 독립적인 현물 테스트넷(Spot Testnet)을 운영합니다:

# 테스트넷 설정
BASE_URL = "https://testnet.binance.vision"
# API Key는 testnet.binance.vision에서 별도로 등록해야 함

테스트넷의 주문, 취소, 잔액 조회는 메인넷과 완전히 동일하게 작동하지만, 코인 가격은 실제 시장과 동기화되지 않습니다. 모든 새 코드는 테스트넷에서 24시간 동안 구동해 본 후 메인넷으로 전환하는 것을 권장합니다.

7. 자주 묻는 질문 FAQ

Q1: 주문 시 filter failure: LOT_SIZE 오류가 발생하는 이유는 무엇인가요?

A: 수량이 해당 거래 페어의 stepSize(최소 단계)에 맞지 않기 때문입니다. 예를 들어 BTCUSDT의 stepSize가 0.00001이라면 0.000005와 같은 수량으로는 주문할 수 없습니다. /api/v3/exchangeInfo를 호출하여 각 페어의 LOT_SIZE / MIN_NOTIONAL / PRICE_FILTER 규칙을 확인하고 반올림 처리를 하세요.

Q2: 현물 API에서 모든 미체결 주문을 한 번에 취소할 수 있나요?

A: 예, 가능합니다. DELETE /api/v3/openOrders?symbol=BTCUSDT를 호출하면 해당 페어의 모든 미체결 주문이 한 번에 취소됩니다(가중치 1). 단, 모든 페어에 걸친 일괄 취소는 지원하지 않습니다.

Q3: 일괄 주문(Batch Order)은 어떻게 하나요?

A: 현물 API에는 네이티브 일괄 주문 인터페이스가 없으므로 POST /api/v3/order를 병렬로 여러 번 호출해야 합니다. 단, 10초당 주문 상한 100건을 주의하세요. 선물 API에는 한 번에 최대 5건까지 가능한 /fapi/v1/batchOrders가 있습니다.

Q4: SIDE와 type을 조합하여 어떤 전략 주문이 가능한가요?

A: 주요 유형으로는 LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT, LIMIT_MAKER가 있습니다. 스탑 로스(손절) 주문의 경우 stopPrice를 추가로 전달해야 합니다.

더 많은 선물 API 관련 내용은 카테고리 가이드의 'API 연동' 카테고리 전체 목록에서 확인하세요.