암호화폐 거래소에서 제공하는 API는 단순히 가격을 확인하는 수준을 넘어, 연구와 데이터 분석에 활용할 수 있는 중요한 도구이다. CEX 거래소의 경우 온체인에 입출금 내역만 기록되기 때문에 정교한 분석을 위해서는 별도의 접근이 필요하다. 바이낸스(Binance)는 개인 거래 데이터와 시장 데이터를 모두 제공하는 특징이 있으며, 해당 글에서는 시장 데이터를 중심으로 정리 되었다.
- 참고 자료
- 바이낸스 공식 API 문서 : https://developers.binance.com/docs/binance-spot-api-docs
- cex.io api 문서 : https://docs.cex.io
환경 세팅 (선택)
분석 환경은 Python 3.11 환경을 기준으로 한다. 새로운 가상환경을 만드는 것이 권장되지만, 기존에 사용하는 파이썬 환경에 바로 패키지를 설치해도 무방하다
- PowerShell, VS Code/Cursor 터미널, Mac/Linux 터미널에서 모두 실행 가능하다.
conda create -n binance311 python=3.11 -y conda activate binance311 pip install -U pip
환경을 활성화한 후 필요한 기본 패키지를 설치한다.
pip install requests websockets pandas python-dotenv
- requests : REST API 요청을 보내고 응답을 받는 데 사용한다.
- websockets : 실시간 시세와 체결 데이터를 스트리밍으로 수집할 때 사용한다.
- pandas : 수집한 데이터를 데이터프레임 형태로 정리하고 분석할 때 사용한다.
- python-dotenv : API 키와 같은 민감한 정보를
.env파일로 관리할 때 사용한다
이 환경을 기반으로 바이낸스 API에 접근하여 시장 데이터를 수집하고, 데이터프레임으로 가공하여 분석하는 과정을 단계별로 진행한다.
바이낸스 API 특징
바이낸스는 세계 최대 규모의 암호화폐 거래소 중 하나로, 다양한 데이터를 제공하는 API를 운영한다. 크게 퍼블릭(Public) API와 프라이빗(Private) API로 나뉜다. API 응답 데이터는 대부분 JSON 형식으로 제공되며, 파이썬에서는 requests나 pandas를 이용해 손쉽게 처리할 수 있다.
| 구분 | 주요 특징 | 제공 데이터 | 인증 필요 여부 |
|---|---|---|---|
| 퍼블릭 API | 시장 데이터 중심, 누구나 접근 가능 | 시세, 호가(Order Book), 최근 체결(Trades), 캔들(Klines) | ❌ 필요 없음 |
| 프라이빗 API | 개인 계정 데이터 접근 | 잔고 조회, 주문 이력, 거래 내역, 주문 생성/취소 | ✅ API Key + Secret Key 필요 |
퍼블릭 API 테이블 정보
바이낸스에서 제공하는 퍼블릭 API는 인증 없이 접근 가능하며, 연구나 데이터 분석에 가장 많이 활용되는 자원이다. 응답 데이터는 JSON 형식으로 제공되고, 이를 파이썬의 requests나 pandas 라이브러리로 쉽게 처리할 수 있다. 퍼블릭 API는 크게 시세 데이터, 호가 및 체결 데이터, 캔들 데이터, 시스템 정보로 나눌 수 있으며, 각각의 데이터는 특정한 엔드포인트(endpoint)를 통해 호출된다.
퍼블릭 API는 용도에 따라 다양한 데이터를 제공하는데, 연구 목적에서 특히 많이 활용되는 정보는 현재가, 24시간 통계, 호가창, 체결, 캔들 데이터 등이다. 이외에도 거래소 시스템 정보나 평균가와 같은 참고용 데이터도 제공된다. 아래 표는 퍼블릭 API에서 제공하는 대표적인 테이블 정보들을 정리한 것이다. 각 항목에는 엔드포인트, 설명, 주요 필드(내용) 를 함께 표시하였다.
주요 퍼블릭 API 요약
| 구분 | 엔드포인트 | 설명 | 주요 필드(내용) |
|---|---|---|---|
| 서버 정보 | /api/v3/time | 서버 현재 시각 조회 | serverTime(서버 시각, ms) |
| 거래소 정보 | /api/v3/exchangeInfo | 거래쌍(symbol), 상태, 최소 단위 등 | symbol(거래쌍), status(거래 상태), baseAsset(기준 자산), quoteAsset(상대 자산) |
| 현재가 | /api/v3/ticker/price | 특정 거래쌍의 최신 체결 가격 | symbol(거래쌍), price(현재 가격) |
| 24시간 통계 | /api/v3/ticker/24hr | 최근 24시간 가격 변동, 거래량 | priceChange(가격 변화), priceChangePercent(변동률 %), highPrice(고가), lowPrice(저가), volume(거래량), quoteVolume(거래대금) |
| 평균가 | /api/v3/avgPrice | 최근 거래 기반 평균가 | mins(계산 기준 분), price(평균 가격) |
| 최우선 호가 | /api/v3/ticker/bookTicker | 매수·매도 최우선 호가 | symbol(거래쌍), bidPrice(최고 매수호가), bidQty(매수 수량), askPrice(최저 매도호가), askQty(매도 수량) |
| 호가창 | /api/v3/depth | 매수·매도 호가 리스트 | lastUpdateId(호가 스냅샷 ID), bids(매수 리스트), asks(매도 리스트) |
| 최근 체결 | /api/v3/trades | 가장 최근 거래 내역 | id(체결 ID), price(체결 가격), qty(체결 수량), time(체결 시각, ms), isBuyerMaker(메이커 여부) |
| 집계 체결 | /api/v3/aggTrades | 일정 기준 묶음 거래 | a(집계 ID), p(가격), q(수량), T(체결 시각, ms), m(메이커 여부) |
| 캔들(Klines) | /api/v3/klines | 일정 시간 단위 OHLCV | openTime(시작 시각, ms), open(시가), high(고가), low(저가), close(종가), volume(거래량), closeTime(종료 시각, ms) |
- 엔드포인트란, API에서 특정 기능이나 자원에 접근할 수 있는 고유한 URL 경로를 의미한다.
GET https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT
https://api.binance.com→ Base URL/api/v3/ticker/price→ 엔드포인트?symbol=BTCUSDT→ 쿼리 파라미터
- 참고 링크
- Binance Spot API Docs (REST) : https://developers.binance.com/docs/binance-spot-api-docs
- 데이터 예시 (캔들, 호가, 체결 등) : https://binance-docs.github.io/apidocs/spot/en/#market-data-endpoints
바이낸스 퍼블릭 API 데이터 조회하기
퍼블릭 API는 인증이 필요 없기 때문에 단순한 GET 요청으로 데이터를 확인할 수 있다. 파이썬에서는 requests 라이브러리를 이용해 API 요청을 보내고, 응답을 JSON 형식으로 받아 처리한다. 또한 pandas를 사용하면 데이터를 테이블 형태로 변환하여 분석할 수 있다.
라이브러리
import requests import pandas as pd
- requests : API 요청을 보내고 응답(JSON)을 받아오는 데 사용한다.
- pandas : JSON 데이터를 표 형태(DataFrame)로 변환하여 분석하기 쉽게 만들어준다.
요청-응답 기본 구조
url: 호출할 엔드포인트의 절대 경로를 담는다.params: 쿼리 파라미터를 딕셔너리로 담는다(자동으로?key=value형태로 인코딩됨).requests.get(url, params=...): HTTP GET 요청을 보낸다(필요 시timeout을 함께 지정한다).res.json(): 응답 본문을 JSON → 파이썬 객체(dict/list)로 변환한다.print(...): 변환된 데이터를 확인한다.- 참고: 에러 상황을 대비해
res.raise_for_status()로 HTTP 오류를 바로 감지하는 것이 좋다. 또한 타임아웃을 지정하면 네트워크 지연으로 무한 대기하는 상황을 피할 수 있다.
데이터 호출하기
- 현재가 조회 하기
- 단일 심볼 지정 시: 한 개 객체 반환
- 심볼 생략 시: 모든 심볼 리스트 반환 (대량 데이터 주의)
# 바이낸스 현재가(Ticker Price) 데이터 조회 예제
url = "https://api.binance.com/api/v3/ticker/price"
params = {"symbol": "BTCUSDT"}
# symbol: 조회할 거래쌍 (여기서는 BTC/USDT)
res = requests.get(url, params=params, timeout=10)
res.raise_for_status() # HTTP 오류 발생 시 예외 발생
data = res.json() # 응답(JSON)을 파이썬 딕셔너리로 변환
print(data) # {'symbol': 'BTCUSDT', 'price': '27123.45'}
- 호가창 조회
limit: 조회 개수 지정 (기본 100, 최대 5000)bids= 매수 리스트,asks= 매도 리스트
# 바이낸스 호가창(Order Book Depth) 데이터 조회 예제
url = "https://api.binance.com/api/v3/depth"
params = {"symbol": "BTCUSDT", "limit": 5}
# symbol: 조회할 거래쌍 (여기서는 BTC/USDT)
# limit: 조회할 호가 개수 (기본 100, 최대 5000)
# 여기서는 상위 5개 매수/매도 호가만 가져옴
res = requests.get(url, params=params, timeout=10)
res.raise_for_status() # HTTP 오류 발생 시 예외 발생
# 응답(JSON)을 그대로 출력
# 'bids' = 매수 호가 리스트, 'asks' = 매도 호가 리스트
# 각 항목은 ["가격", "수량"] 형식으로 반환됨
print(res.json())
- 최근 체결 조회
- 최근 거래 내역을 최대 1000건까지 조회 가능
id,price,qty,time,isBuyerMaker필드 포함
# 바이낸스 최근 체결(Recent Trades) 데이터 조회 예제
url = "https://api.binance.com/api/v3/trades"
params = {"symbol": "BTCUSDT", "limit": 5}
# symbol: 조회할 거래쌍 (여기서는 BTC/USDT)
# limit: 조회할 체결 건수 (기본 500, 최대 1000)
res = requests.get(url, params=params, timeout=10)
res.raise_for_status() # HTTP 오류 발생 시 예외 발생
# 응답(JSON)을 그대로 출력
# 리스트 형식으로 최근 체결 n건이 반환됨
print(res.json())
- 캔들 데이터 조회
# 바이낸스 캔들(Klines) 데이터 조회 예제
url = "https://api.binance.com/api/v3/klines"
params = {"symbol": "BTCUSDT", "interval": "1h", "limit": 5}
# symbol: 조회할 거래쌍 (여기서는 BTC/USDT)
# interval: 캔들 주기 (1시간 단위)
# limit: 가져올 데이터 개수 (여기서는 최근 5개 캔들)
res = requests.get(url, params=params, timeout=10)
res.raise_for_status() # HTTP 오류 발생 시 예외 발생
# 응답 데이터를 DataFrame으로 변환하기 위한 컬럼 정의
cols = ["openTime","open","high","low","close","volume",
"closeTime","quoteAssetVolume","trades",
"takerBuyBase","takerBuyQuote","ignore"]
df = pd.DataFrame(res.json(), columns=cols)
# JSON 응답을 DataFrame으로 변환
# 응답은 리스트 형식으로, 각 요소가 하나의 캔들을 의미함
# openTime, closeTime을 사람이 읽을 수 있는 datetime으로 변환
df["openTime"] = pd.to_datetime(df["openTime"], unit="ms", utc=True)
df["closeTime"] = pd.to_datetime(df["closeTime"], unit="ms", utc=True)
# 주요 열만 출력 (시각, 시가, 고가, 저가, 종가, 거래량)
print(df[["openTime","open","high","low","close","volume"]])
데이터 호출 시 주의사항
- 호출 횟수 제한
- REST API는 계정·엔드포인트별로 초당 약 10회 내외로 제한된다. (정확한 한도는 엔드포인트마다 다르므로 공식 문서 참고 필요)
- 제한을 초과하면 HTTP 429 Too Many Requests 오류가 발생하며, 과도할 경우 일시적으로 IP 차단될 수 있다.
- WebSocket은 구독 가능한 스트림 수에 제한이 있으며, 동시에 여러 채널을 열 경우 주의가 필요하다.
- 데이터 조회 제한
- 캔들(Klines): 한 번에 최대 1000개까지 조회 가능
- 체결(Trades): 기본 500개, 최대 1000개까지 조회 가능
- 호가창(Depth): 단계별 최대 5000개까지 제공
- 데이터 특성
- 캔들(Klines) 데이터는 시계열 OHLCV 구조이며, 긴 기간을 모으려면 startTime/endTime을 조정해 여러 번 호출해야 한다.
- 체결 데이터는 짧은 기간만 제공되므로 장기 거래내역은 Binance Data Portal에서 덤프 데이터를 활용하는 것이 효율적이다.
- WebSocket은 실시간 스트리밍에 적합하지만, 연결이 끊길 경우 재연결 및 데이터 보정 로직이 필요하다.
- 에러 처리
res.raise_for_status()로 HTTP 오류를 즉시 감지한다.- 429 오류 발생 시 딜레이(backoff) 후 재시도해야 한다.
timeout옵션을 지정해 네트워크 지연에 대비한다.