저는 HolySheep AI 기술 블로그를 통해 다양한 API 통합 가이드를 제공하고 있습니다. 오늘은 cryptocurrency 거래소 중 세계 3위 거래량을 보유한 OKX의 API를 사용하여 인증하고 데이터를 조회하는 방법을 초보자 눈높이에서 자세히 설명드리겠습니다.
이 튜토리얼을 마치면 OKX API 키를 생성하고, Python을 사용하여 시세 데이터를 가져오며, 트레이딩 봇의 기초를 구축할 수 있게 됩니다.
1. OKX API란 무엇인가?
API(Application Programming Interface)는 쉽게 말해 "프로그램들이 서로 대화하는 방법"입니다. OKX API를 사용하면 다음과 같은 것들을 할 수 있습니다:
- 실시간 시세 데이터 조회
- 거래 내역 확인
- 주문 넣고 취소
- 포트폴리오 잔고 확인
- 자동 트레이딩 봇 개발
【스크린샷 힌트】OKX 웹사이트 우측 상단 "거래소" 메뉴에서 "API"를 클릭하면 API 관리 페이지로 이동합니다. 이 페이지는 나중에 자주 사용하게 될 중요한 페이지입니다.
2. OKX API 키 생성하기 (단계별)
API를 사용하려면 먼저 OKX에서 API 키를 발급받아야 합니다. 아래 단계를 따라하세요.
2.1 OKX 계정 생성 및 실명인증
아직 OKX 계정이 없다면 OKX 공식 웹사이트에서 가입하세요. 한국에서는 KYC(실명인증)가 필요하므로 신분증 준비를 해두세요.
2.2 API 관리 페이지 접근
- OKX에 로그인 후 우측 상단 프로필 아이콘 클릭
- "API" 메뉴 선택
- "API Key 생성" 버튼 클릭
2.3 API 키 설정
【스크린샷 힌트】API 생성 페이지에서 다음 항목을 설정합니다:
📋 API 키 설정 양식:
┌─────────────────────────────────────────┐
│ API Key 이름: my_trading_bot │
│ passphrase: 마이패스워드123 │
│ │
│ 권한 설정 (중요!): │
│ □ 읽기 전용 (시세·잔고 조회) │
│ ☑ 선물/현물 거래 │
│ □ 출금 가능 │
│ │
│ IP 허용 목록: 비워두면 모든 IP 허용 │
│ ※ 보안 강화를 위해 IP 제한 권장 │
└─────────────────────────────────────────┘
【중요】출금 권한은 절대 체크하지 마세요! 해킹 시 모든 자산이 도난될 수 있습니다. 저도 처음에는 읽기 전용으로만 시작해서 문제가 없는 것을 확인한 후 점진적으로 권한을 늘렸습니다.
2.4 API 키 정보 저장
생성 완료 후 다음과 같은 정보가 표시됩니다:
✅ 생성 완료! 아래 정보를 안전한 곳에 보관하세요:
┌──────────────────────────────────────────────────┐
│ API Key: a1b2c3d4e5f6g7h8i9j0 │
│ Secret Key: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6 │
│ Passphrase: 마이패스워드123 │
│ │
│ ⚠️ Secret Key는 이 화면을 벗어나면 다시 볼 수 │
│ 없습니다. 반드시 지금 저장하세요! │
└──────────────────────────────────────────────────┘
이 세 가지 정보(API Key, Secret Key, Passphrase)를 안전한 곳에 보관하세요. 저는 1Password에 암호화해서 저장합니다.
3. API 인증 원리 이해하기
API를 호출할 때 단순히 키를 보내는 것이 아니라, 전자서명을 생성해야 합니다. 이는银行卡처럼 "본인 확인 절차"와 같습니다.
3.1 HMAC-SHA256 서명이란?
HMAC-SHA256은 "메시지를 비밀 키로 암호화하는 방법"입니다. 과정은 다음과 같습니다:
- 요청 정보(시간, 요청 내용)를 하나의 문자열로 합침
- 비밀 키로 그 문자열을 암호화
- 암호화된 결과를 함께 보냄
- 서버가 같은 방법으로 암호화하여 일치 여부 확인
3.2 OKX API 인증 헤더 구성
📨 요청 헤더 구성 요소:
timestamp: ISO 8601 형식 (예: 2024-01-15T09:30:00.123Z)
sign: HMAC-SHA256 서명 결과
key: API Key
passphrase: 생성 시 설정한 패스프레이즈
4. Python으로 OKX API 호출하기
이제 실제 코드를 작성해 보겠습니다. Python 환경이 없다면 python.org에서 다운로드하세요.
4.1 필요한 라이브러리 설치
터미널(명령 프롬프트)에서 실행하세요:
pip install requests
requests 라이브러리는 HTTP 요청을 보내는 표준 도구입니다.
4.2 기본 OKX API 클래스 구현
"""
OKX API 기본 연동 클래스
작성자: HolySheep AI 기술팀
"""
import requests
import json
import time
import hmac
import hashlib
import base64
from datetime import datetime
class OKXAPI:
"""OKX 거래소 API 연동 클래스"""
def __init__(self, api_key, secret_key, passphrase, flag="0"):
"""
초기화: API 자격 증명 저장
매개변수:
api_key: OKX에서 발급받은 API 키
secret_key: 시크릿 키
passphrase: 패스프레이즈
flag: "0" 실전거래, "1" 데모거래
"""
self.api_key = api_key
self.secret_key = secret_key
self.passphrase = passphrase
self.flag = flag
self.base_url = "https://www.okx.com"
def _get_sign(self, timestamp, method, request_path, body=""):
"""
HMAC-SHA256 서명 생성 (핵심 인증 로직)
서명 문자열 형식: timestamp + method + request_path + body
"""
message = timestamp + method + request_path + body
mac = hmac.new(
self.secret_key.encode('utf-8'),
message.encode('utf-8'),
hashlib.sha256
)
return base64.b64encode(mac.digest()).decode('utf-8')
def _get_headers(self, method, request_path, body=""):
"""요청 헤더 생성"""
timestamp = datetime.utcnow().isoformat() + 'Z'
sign = self._get_sign(timestamp, method, request_path, body)
headers = {
'Content-Type': 'application/json',
'OK-ACCESS-KEY': self.api_key,
'OK-ACCESS-SIGN': sign,
'OK-ACCESS-TIMESTAMP': timestamp,
'OK-ACCESS-PASSPHRASE': self.passphrase,
'x-simulated-trading': '0' if self.flag == '0' else '1'
}
return headers
def _request(self, method, request_path, params=None):
"""API 요청 보내기 (공통 메서드)"""
url = self.base_url + request_path
if method == 'GET' and params:
url += '?' + '&'.join([f"{k}={v}" for k, v in params.items()])
body = json.dumps(params) if method in ['POST', 'PUT'] and params else ""
headers = self._get_headers(method, request_path, body)
print(f"📡 요청 URL: {url}")
print(f"📋 요청 메서드: {method}")
if method == 'GET':
response = requests.get(url, headers=headers)
elif method == 'POST':
response = requests.post(url, headers=headers, data=body)
else:
response = requests.request(method, url, headers=headers, data=body)
result = response.json()
# 응답 디버깅
if result.get('code') == '0':
print(f"✅ 성공: {result.get('msg', 'OK')}")
else:
print(f"❌ 오류 코드: {result.get('code')}, 메시지: {result.get('msg')}")
return result
# ============ Public API (인증 불필요) ============
def get_ticker(self, inst_id="BTC-USDT"):
"""단일 거래대상 시세 조회"""
return self._request('GET', '/api/v5/market/ticker', {'instId': inst_id})
def get_all_tickers(self):
"""전체 거래대상 시세 조회"""
return self._request('GET', '/api/v5/market/tickers', {'instType': 'SPOT'})
def get_candles(self, inst_id="BTC-USDT", bar="1H", limit="100"):
"""OHLC 캔들sticks 데이터 조회"""
return self._request('GET', '/api/v5/market/candles', {
'instId': inst_id,
'bar': bar,
'limit': limit
})
# ============ Private API (인증 필요) ============
def get_account_balance(self):
"""계정 잔고 조회"""
return self._request('GET', '/api/v5/account/balance')
def get_order_book(self, inst_id="BTC-USDT", sz="10"):
"""호가창(오더북) 조회"""
return self._request('GET', '/api/v5/market/books', {
'instId': inst_id,
'sz': sz
})
============ 사용 예제 ============
if __name__ == "__main__":
# ⚠️ 실제 API 키로 교체하세요
api = OKXAPI(
api_key="YOUR_API_KEY",
secret_key="YOUR_SECRET_KEY",
passphrase="YOUR_PASSPHRASE",
flag="0" # "0" 실전, "1" 데모
)
# 1. BTC/USDT 시세 조회
print("\n" + "="*50)
print("BTC/USDT 현재 시세")
print("="*50)
btc_ticker = api.get_ticker("BTC-USDT")
if btc_ticker.get('data'):
data = btc_ticker['data'][0]
print(f"💰 현재가: ${float(data['last']):,.2f}")
print(f"📈 24시간 고가: ${float(data['high24h']):,.2f}")
print(f"📉 24시간 저가: ${float(data['low24h']):,.2f}")
print(f"🔄 24시간 거래량: {float(data['vol24h']):,.2f} BTC")
이 코드를 okx_api.py로 저장하고 실행하면 BTC/USDT 시세를 확인할 수 있습니다.
실행 방법
python okx_api.py
【실행 결과 예시】
📡 요청 URL: https://www.okx.com/api/v5/market/ticker?instId=BTC-USDT
📋 요청 메서드: GET
✅ 성공: OK
==================================================
BTC/USDT 현재 시세
==================================================
💰 현재가: $67,234.50
📈 24시간 고가: $68,150.00
📉 24시간 저가: $65,890.00
🔄 24시간 거래량: 23,456.78 BTC
5. 주요 API 엔드포인트 정리
5.1 공개 API (인증 불필요)
다양한 시세 조회 예제
1. 특정 거래쌍 시세
api.get_ticker("ETH-USDT") # 이더리움 현재가
2. 1시간봉 캔들 데이터 (최근 100개)
eth_candles = api.get_candles("ETH-USDT", bar="1H", limit="100")
3. 호가창 조회 (매수/매도 호가)
api.get_order_book("BTC-USDT", sz="20")
4. 여러 거래쌍 동시 조회
api.get_all_tickers() # 전체 SPOT 시세
5.2 인증 필요 API (잔고 조회)
계정 관련 API는 반드시 API 키 설정 필요
USDT 잔고 조회
balance = api.get_account_balance()
if balance.get('data'):
for asset in balance['data'][0]['details']:
if float(asset.get('availBal', 0)) > 0:
currency = asset['ccy']
available = float(asset['availBal'])
frozen = float(asset.get('frozenBal', 0))
total = available + frozen
print(f"💎 {currency}: 사용가능 {available:.4f} / 잠김 {frozen:.4f} / 총 {total:.4f}")
6. 실전 프로젝트: 간단한 트레이딩 봇 기초
API 활용의 진정한 힘은 자동화에 있습니다. 아래는 가격이 특정 임계값을 넘으면 알림을 보내는 간단한 모니터링 봇입니다.
"""
OKX 가격 알림 봇
- BTC 가격이 $70,000 이상일 때 알림
- 1분마다 자동 확인
"""
import time
import os
환경변수에서 API 키 로드 (보안 강화)
API_KEY = os.environ.get('OKX_API_KEY', 'YOUR_API_KEY')
SECRET_KEY = os.environ.get('OKX_SECRET_KEY', 'YOUR_SECRET_KEY')
PASSPHRASE = os.environ.get('OKX_PASSPHRASE', 'YOUR_PASSPHRASE')
알림 임계값 설정
ALERT_PRICE = 70000 # $70,000
CHECK_INTERVAL = 60 # 60초마다 확인
def price_monitor():
"""가격 모니터링 루프"""
api = OKXAPI(API_KEY, SECRET_KEY, PASSPHRASE)
print(f"🔔 BTC 가격 모니터링 시작")
print(f" 임계값: ${ALERT_PRICE:,}")
print(f" 확인 주기: {CHECK_INTERVAL}초")
print("-" * 40)
while True:
try:
result = api.get_ticker("BTC-USDT")
if result.get('data'):
data = result['data'][0]
current_price = float(data['last'])
price_change = float(data['sodUtc0']) # 하루 시작가 대비
change_pct = ((current_price - price_change) / price_change) * 100
# 화면에 현재 상태 표시
status = "🟢 상승" if change_pct > 0 else "🔴 하락"
print(f"[{time.strftime('%H:%M:%S')}] BTC: ${current_price:,.2f} | {status} {change_pct:+.2f}%")
# 임계값 도달 시 알림
if current_price >= ALERT_PRICE:
print(f"\n" + "="*40)
print(f"🎉 알림! BTC가 ${ALERT_PRICE:,} 이상 도달!")
print(f" 현재가: ${current_price:,.2f}")
print("="*40 + "\n")
# 실제 알림 보내기 (이메일, 슬랙 등 연동 가능)
time.sleep(CHECK_INTERVAL)
except KeyboardInterrupt:
print("\n⛔ 모니터링 종료")
break
except Exception as e:
print(f"❌ 오류 발생: {e}")
time.sleep(5) # 오류 시 5초 후 재시도
if __name__ == "__main__":
price_monitor()
이 봇을 실행하면 1분마다 BTC 가격을 확인하고 $70,000 이상이면 알림을 표시합니다.
7. HolySheep AI 활용: 다중 거래소 통합
여러 거래소의 API를 동시에 사용해야 한다면 관리가 복잡해집니다. HolySheep AI를 사용하면 단일 API 키로 다양한 AI 모델과 서비스(여기에 포함된 REST API 연동 패턴도 적용 가능)를 통합 관리할 수 있어 개발 생산성이 크게 향상됩니다.
특히 HolySheep AI의 특징은:
- 해외 신용카드 없이 로컬 결제 가능
- 단일 엔드포인트로 여러 서비스 통합
- 비용 최적화 및 실시간 모니터링 대시보드
AI API와 거래소 API를 함께 사용하는 하이브리드 전략(AI 기반 시장 분석 + 자동 거래)을 구축할 때 HolySheep의 통합 접근 방식이 매우 유용합니다.
자주 발생하는 오류와 해결책
오류 1: "签名失败" (Sign failed) - 잘못된 서명
❌ 오류 발생 시 흔한 원인들:
1. Secret Key 형식 문제
잘못된 예시
secret = "A1B2C3D4" # 따옴표 안에 따옴표
✅ 올바른 예시
secret = "A1B2C3D4E5F6G7H8I9J0" # 정확한 키 복사
2. timestamp 형식 불일치
ISO 8601 형식 + 'Z' 필수
timestamp = datetime.utcnow().isoformat() + 'Z'
결과: "2024-01-15T09:30:00.123Z"
3. Body 문자열 형식
GET 요청 시 body는 빈 문자열
sign_string = timestamp + method + request_path + ""
POST 요청 시 body는 JSON 문자열
body = json.dumps(params)
sign_string = timestamp + method + request_path + body
오류 2: "认证失败" (Auth failed) - 인증 정보 오류
API 키, Secret, Passphrase 중 하나가 잘못된 경우
확인 방법 1: 공백 문자열 여부 체크
if not api_key or not api_key.strip():
print("❌ API Key가 비어있습니다")
확인 방법 2: 길이 검증
OKX API Key: 일반적으로 32자
OKX Secret Key: 일반적으로 64자
if len(api_key) < 30:
print("❌ API Key 길이가 짧습니다. 다시 확인하세요.")
확인 방법 3: 환경변수에서 올바르게 로드하는지 확인
import os
api_key = os.environ.get('OKX_API_KEY')
if api_key is None:
print("❌ 환경변수 OKX_API_KEY가 설정되지 않았습니다")
print(" 터미널에서 설정: export OKX_API_KEY='your_key'")
✅ 올바른 환경변수 설정 방법
Linux/Mac:
export OKX_API_KEY="your_api_key"
export OKX_SECRET_KEY="your_secret_key"
export OKX_PASSPHRASE="your_passphrase"
Windows (명령 프롬프트):
set OKX_API_KEY=your_api_key
set OKX_SECRET_KEY=your_secret_key
set OKX_PASSPHRASE=your_passphrase
Windows (PowerShell):
$env:OKX_API_KEY="your_api_key"
오류 3: "接口不存在" (Endpoint not found) - 잘못된 엔드포인트
❌ 흔한 실수들:
1. URL 경로 오타
wrong_url = "https://www.okx.com/api/v5/market/tikers" # tiker 오타!
correct_url = "https://www.okx.com/api/v5/market/ticker"
2. 필수 파라미터 누락
ticker 요청 시 instId 필수
api._request('GET', '/api/v5/market/ticker')
❌ TypeError: instId 파라미터 필요
✅ 올바른 호출
api._request('GET', '/api/v5/market/ticker', {'instId': 'BTC-USDT'})
3. 거래쌍 형식 오류
올바른 형식: BTC-USDT (대시 사용)
잘못된 형식: BTC_USDT (밑줄), BTC/USDT (슬래시), BTCUSDT (구분자 없음)
✅ 사용 가능한 거래쌍 확인
valid_pairs = ["BTC-USDT", "ETH-USDT", "SOL-USDT", "DOGE-USDT"]
오류 4: Rate Limit 초과 (429 Too Many Requests)
API 호출 제한에 도달한 경우
import time
def request_with_retry(api_func, max_retries=3, delay=1):
"""재시도 로직이 포함된 API 호출"""
for attempt in range(max_retries):
try:
result = api_func()
# Rate Limit 체크
if hasattr(result, 'headers'):
remaining = result.headers.get('X-RateLimit-Remaining')
if remaining and int(remaining) < 5:
print(f"⚠️ Rate Limit 근접. 60초 대기...")
time.sleep(60)
return result
except Exception as e:
if '429' in str(e):
wait_time = 2 ** attempt # 지수 백오프: 1, 2, 4초
print(f"⏳ Rate Limit. {wait_time}초 후 재시도 ({attempt+1}/{max_retries})")
time.sleep(wait_time)
else:
raise
else:
print("❌ 최대 재시도 횟수 초과")
return None
오류 5: 네트워크 연결 오류
네트워크 불안정 시 처리
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
def create_session_with_retry():
"""자동 재시도 기능이 포함된 세션 생성"""
session = requests.Session()
retry_strategy = Retry(
total=3,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["HEAD", "GET", "OPTIONS", "POST"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)
session.mount("http://", adapter)
return session
사용 예시
session = create_session_with_retry()
response = session.get("https://www.okx.com/api/v5/market/ticker?instId=BTC-USDT")
보안 모범 사례
- API 키를 코드에 직접 입력하지 마세요. 환경변수나 시크릿 매니저 사용
- 출금 권한은 절대 활성화하지 마세요. 읽기 전용으로 시작
- IP 허용 목록을 설정하세요. 본인 IP만 허용
- 별도 트레이딩 전용 서브 계정 사용을 고려하세요. 메인 계정 보호
- API 키를 정기적으로 교체하세요. 분기 1회 이상
다음 단계
이 튜토리얼을 완료했다면 다음과 같은 다음 단계들을 탐색할 수 있습니다:
- 주문 넣기: Market order, Limit order 구현
- 거래 내역 조회: 과거 거래 내역 필터링
- 웹소켓 연동: 실시간 시세 스트리밍
- 고급 주문: Stop-loss, Take-profit,OCO 주문
OKX 공식 문서(OKX API Documentation)에서 더 많은 엔드포인트와 상세 정보를 확인할 수 있습니다.
결론
OKX API는 cryptocurrency 트레이딩 자동화와 시장 데이터 분석을 위한 강력한 도구입니다. 이 튜토리얼에서 다룬 인증 원리와 데이터 조회 방법을 이해하면, 어떤 거래소 API든 비슷한 패턴으로 접근할 수 있습니다.
자동화 투자는 편리하지만, 특히 cryptocurrency 시장은 변동성이 높으므로 반드시 충분한 테스트 후 실전에 투입하시기 바랍니다. 데모 거래 모드(flag="1")로 충분히 연습하세요.
HolySheep AI에서는 AI API 통합과 비용 최적화를 위한 다양한 기술 가이드를 제공하고 있습니다. AI 기반 시장 분석과 거래 자동화를 결합한 하이브리드 전략을 구축하고 싶다면 HolySheep의 통합 플랫폼을 활용해보세요.