크라켄 API 사용법: 트레이딩 완벽 가이드

선물 계약 및 현물 거래를 관리하는 입증된 API를 통해 세계에서 가장 유동적인 암호화폐 거래소 중 하나에 접근할 수 있다고 상상해 보세요. Kraken은 바로 그것을 제공합니다. 2011년에 설립되어 190개국 1천만 명 이상의 사용자에게 서비스를 제공하며 200개 이상의 거래 쌍에서 광범위한 유동성을 갖춘 거래소에 WebSocket 및 REST 인터페이스를 제공합니다.

암호화폐 거래 API는 두 가지 범주로 나뉩니다. 개인 사용자의 편의를 위해 설계된 API와 기관의 신뢰성을 위해 구축된 API입니다. 많은 거래소는 API 안정성보다 모바일 앱을 우선시하여, 알고리즘 전략을 제한하는 속도 제한과 기능 출시보다 뒤처지는 문서를 초래합니다. Kraken은 거래량에 따른 계층형 API 접근, 포괄적인 샌드박스 환경, 고빈도 거래자를 위한 전용 엔드포인트를 제공하여 이러한 마찰 지점을 제거합니다. 여러분은 취미용 스크립트에서 기관급 시스템으로 확장되는 자동화된 전략을 구축할 수 있습니다.

목차:

Kraken의 API 아키텍처 이해
인증 및 API 키 설정
REST API를 이용한 현물 거래
WebSocket을 이용한 실시간 데이터
선물 거래 및 고급 기능
결론

💡

자동화된 암호화폐 거래 시스템을 구축하려면 REST 및 WebSocket 엔드포인트 전반에 걸쳐 신뢰할 수 있는 API 테스트가 필요합니다. Apidog는 암호화폐 거래소를 위해 특별히 설계된 시각적 API 테스트, 자동 문서 생성 및 팀 협업 기능을 제공합니다. Kraken API 개발을 간소화하려면 Apidog를 무료로 사용해 보세요—신용카드 정보가 필요 없습니다.

button

Kraken의 API 아키텍처 이해

Kraken은 현물 REST, 선물 REST, WebSocket의 세 가지 개별 API 생태계를 운영합니다. 이러한 아키텍처를 이해하면 올바른 통합 경로를 선택하는 데 도움이 됩니다.

현물 REST API

현물 REST API는 Kraken의 핵심 거래소 기능에 대한 접근을 제공합니다. 이는 공개 엔드포인트(시장 데이터, 티커 정보, 오더북 깊이)와 비공개 엔드포인트(계정 잔액, 주문 관리, 자금 조달)로 구성됩니다. 모든 요청은 TLS 1.2 이상을 사용하는 HTTPS를 이용합니다.

기본 URL: https://api.kraken.com/0

공개 엔드포인트는 인증이 필요 없습니다. 비공개 엔드포인트는 API 키를 사용하여 HMAC-SHA512 요청 서명을 사용합니다. 응답 형식은 다양합니다. 일부 엔드포인트는 첫 번째 요소가 오류 문자열인 배열을 반환하는 반면(레거시 설계), 최신 엔드포인트는 표준 JSON 객체를 사용합니다.

선물 REST API

Kraken Futures는 현물 거래소와 별개로 자체 API 인프라를 운영합니다. 최대 50배 레버리지를 이용한 암호화폐 무기한 스왑 및 고정 만기 선물을 지원합니다.

기본 URL:

운영 환경: https://futures.kraken.com/api/v3
샌드박스: https://demo-futures.kraken.com/api/v3

선물 API는 현물 API와 비교하여 다른 인증 메커니즘과 엔드포인트 구조를 사용합니다. 현물 거래 자격 증명과 별개로 futures.kraken.com에서 생성된 별도의 API 키가 필요합니다.

WebSocket API

Kraken은 두 개의 WebSocket 서버를 통해 실시간 데이터 스트림을 제공합니다:

공개: wss://ws.kraken.com — 시장 데이터, 오더북, 거래
비공개: wss://ws-auth.kraken.com — 계정 업데이트, 주문 상태, 잔액 변경

REST 폴링과 달리 WebSocket 연결은 데이터가 사용 가능해지는 즉시 푸시하여 지연 시간을 수백 밀리초에서 수십 밀리초로 줄입니다. 공개 서버는 인증이 필요 없으며, 비공개 서버는 REST API를 통해 얻은 WebSocket 토큰이 필요합니다.

속도 제한

Kraken은 계층 기반 속도 제한을 구현합니다:

Starter (초급): 분당 60회 호출 (공개), 분당 30회 호출 (비공개)
Intermediate (중급): 분당 125회 호출 (공개), 분당 60회 호출 (비공개)
Pro (전문가): 30일 거래량에 따라 분당 250회 이상 호출

제한을 초과하면 HTTP 429 오류가 발생하며, 요청을 재개할 수 있는 시점을 나타내는 Retry-After 헤더가 함께 반환됩니다.

인증 및 API 키 설정

Kraken은 nonce 기반 리플레이 보호 기능을 갖춘 HMAC-SHA512 인증을 사용합니다. 이는 다중 스레드 애플리케이션에서 흔히 발생하는 "Invalid nonce" 오류를 피하기 위해 신중한 구현이 필요합니다.

API 키 생성

Kraken 대시보드에서 계정 → 보안 → API로 이동하세요:

"새 키 생성"을 클릭
권한 선택:

조회: 계정 잔액, 미체결 주문, 거래 내역 읽기
거래: 주문 체결 및 취소
출금: 자금 이체 (주의해서 사용)
입금: 입금 주소 및 방법 확인

3. IP 화이트리스트 지정 (운영 환경에 권장)

4. API 키와 비공개 키를 안전하게 저장하세요—Kraken은 비공개 키를 다시 표시하지 않습니다

선물 거래의 경우, futures.kraken.com/settings/api에서 이 과정을 반복하세요. demo-futures.kraken.com의 샌드박스 환경은 별도의 자격 증명을 사용합니다.

HMAC-SHA512 서명 (수동 구현)

SDK를 사용하지 않는 경우, 다음과 같이 인증을 구현하세요:

import requests
import hmac
import hashlib
import base64
import time
import json

class KrakenAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = base64.b64decode(api_secret)
        self.base_url = "https://api.kraken.com"
    
    def generate_signature(self, urlpath, data):
        # Nonce는 이전에 사용된 어떤 nonce보다도 높아야 합니다.
        nonce = str(int(time.time() * 1000))
        data['nonce'] = nonce
        
        # 메시지 생성: nonce + POST 데이터
        message = nonce + json.dumps(data, separators=(',', ':'))
        
        # HMAC-SHA512 서명 생성
        signature = hmac.new(
            self.api_secret,
            urlpath.encode() + hashlib.sha256(message.encode()).digest(),
            hashlib.sha512
        ).hexdigest()
        
        return {
            'API-Key': self.api_key,
            'API-Sign': signature,
            'Content-Type': 'application/x-www-form-urlencoded'
        }, data
    
    def private_request(self, method, params=None):
        urlpath = f'/0/private/{method}'
        data = params or {}
        
        headers, signed_data = self.generate_signature(urlpath, data)
        
        response = requests.post(
            f"{self.base_url}{urlpath}",
            headers=headers,
            data=signed_data
        )
        
        return response.json()

# 사용 예시
kraken = KrakenAuth(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_BASE64_ENCODED_PRIVATE_KEY"
)

# 계정 잔액 가져오기
balance = kraken.private_request('Balance')
print(balance)

중요: Nonce 관리

Kraken은 API 키당 엄격하게 증가하는 nonce를 요구합니다. 동일한 키를 사용하는 여러 스레드나 프로세스가 있는 경우, 충돌이 발생하여 "EAPI:Invalid nonce" 오류가 생성됩니다. 해결책:

각 거래 알고리즘 또는 서비스에 다른 API 키 사용
키 공유가 불가피한 경우 Redis 또는 데이터베이스를 통한 nonce 동기화 구현
충돌 확률을 줄이기 위해 마이크로초 단위 타임스탬프 사용 (Unix 시간을 1000으로 곱함)

공식 SDK

Kraken은 공식 Python 및 Node.js SDK를 제공하며, Go, Rust, Julia 및 기타 언어를 위한 커뮤니티 SDK도 있습니다:

# Python
pip install python-kraken-sdk

# Node.js
npm install @kraken-api/sdk

공식 SDK는 인증, nonce 관리 및 오류 구문 분석을 자동으로 처리합니다. 사용자 지정 HTTP 처리에 대한 특정 요구 사항이 없는 한 공식 SDK를 사용하세요.

REST API를 이용한 현물 거래

현물 REST API는 잘 문서화된 엔드포인트를 통해 포괄적인 거래 기능을 제공합니다.

시장 데이터 (공개)

이용 가능한 거래 쌍 검색:

curl "https://api.kraken.com/0/public/AssetPairs"

티커 정보 가져오기:

curl "https://api.kraken.com/0/public/Ticker?pair=XBTUSD"

Kraken은 비트코인의 경우 BTC 대신 XBT, 일부 레거시 엔드포인트에서는 XXBT, USD 대신 ZUSD와 같은 비표준 쌍 심볼을 사용합니다. 거래하기 전에 항상 AssetPairs 엔드포인트를 사용하여 자산 코드를 확인하세요.

오더북 깊이 가져오기:

curl "https://api.kraken.com/0/public/Depth?pair=XBTUSD&count=10"

계정 잔액 (비공개)

balance = kraken.private_request('Balance')
print(balance)

응답 형식은 자산 코드를 키로 사용합니다 (USD의 경우 ZUSD, 비트코인의 경우 XXBT):

{
  "error": [],
  "result": {
    "ZUSD": "1000.50",
    "XXBT": "0.2500"
  }
}

주문 체결

지정가 매수 주문 체결:

order = kraken.private_request('AddOrder', {
    'pair': 'XBTUSD',
    'type': 'buy',
    'ordertype': 'limit',
    'price': '65000.00',
    'volume': '0.01',
    'oflags': 'post'  # Post-only 플래그
})

print(order)

주문 유형:

market: 이용 가능한 최적 가격으로 즉시 실행
limit: 지정된 가격 또는 더 좋은 가격으로 실행
stop-loss: 가격이 임계값을 넘을 때 시장가 주문 트리거
take-profit: 손절매(stop-loss)의 반대
trailing-stop: 가격 변동을 따라가는 동적 스탑

주문 관리

미체결 주문 목록:

open_orders = kraken.private_request('OpenOrders')
print(open_orders)

주문 취소:

kraken.private_request('CancelOrder', {
    'txid': 'XXXXXX-XXXXXX-XXXXXX'
})

모든 주문 취소 (비상 정지):

kraken.private_request('CancelAll')

거래 내역

체결된 거래 조회:

trades = kraken.private_request('TradesHistory', {
    'start': '1704067200',  # Unix 타임스탬프
    'end': '1706659200'
})

전문가 팁Apidog

WebSocket을 이용한 실시간 데이터

REST 폴링은 알고리즘 거래에 허용할 수 없는 지연 시간을 발생시킵니다. Kraken의 WebSocket API는 실시간 오더북 업데이트, 거래 및 계정 이벤트를 스트리밍합니다.

공개 WebSocket에 연결

const WebSocket = require('ws');

const ws = new WebSocket('wss://ws.kraken.com');

ws.on('open', () => {
  console.log('Kraken 공개 WebSocket에 연결됨');
  
  // BTC/USD 티커 구독
  ws.send(JSON.stringify({
    event: 'subscribe',
    pair: ['XBT/USD'],
    subscription: {
      name: 'ticker'
    }
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  // 티커 형식: [channelID, tickerData, pair, channelName]
  if (Array.isArray(message) && message[2] === 'XBT/USD') {
    const [channelID, ticker, pair, channelName] = message;
    console.log(`BTC 가격: 매수호가 ${ticker.b[0]}, 매도호가 ${ticker.a[0]}`);
  }
});

// 30초마다 하트비트 전송
setInterval(() => {
  ws.send(JSON.stringify({ event: 'ping' }));
}, 30000);

WebSocket 구독은 숫자 채널 ID를 가진 배열 형식으로 데이터를 반환합니다. 데이터를 올바르게 라우팅하려면 이 ID를 구독에 매핑하세요.

오더북 스트리밍

레벨 2 오더북 데이터 구독:

ws.send(JSON.stringify({
  event: 'subscribe',
  pair: ['XBT/USD'],
  subscription: {
    name: 'book',
    depth: 25  // 25, 100, 500 또는 1000 레벨
  }
}));

오더북 피드는 스냅샷을 보낸 다음 증분 업데이트를 보냅니다. 델타를 적용하여 로컬 오더북 상태를 유지하세요:

let orderBook = { asks: {}, bids: {} };

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  if (message[1] === 'as' || message[1] === 'bs') {
    // 스냅샷: 오더북 초기화
    const [channelID, type, asks, bids] = message;
    orderBook.asks = Object.fromEntries(asks.map(([price, volume]) => [price, volume]));
    orderBook.bids = Object.fromEntries(bids.map(([price, volume]) => [price, volume]));
  } else if (message[1] === 'a' || message[1] === 'b') {
    // 업데이트: 델타 적용
    const [channelID, type, delta] = message;
    const side = type === 'a' ? 'asks' : 'bids';
    
    delta.forEach(([price, volume]) => {
      if (volume === '0.00000000') {
        delete orderBook[side][price];
      } else {
        orderBook[side][price] = volume;
      }
    });
  }
});

비공개 WebSocket 인증

REST를 통해 WebSocket 토큰 획득:

token_response = kraken.private_request('GetWebSocketsToken')
token = token_response['result']['token']

비공개 WebSocket에 연결:

const privateWs = new WebSocket('wss://ws-auth.kraken.com');

privateWs.on('open', () => {
  // 인증
  privateWs.send(JSON.stringify({
    event: 'subscribe',
    subscription: {
      name: 'ownTrades',
      token: 'YOUR_WEBSOCKET_TOKEN'
    }
  }));
});

privateWs.on('message', (data) => {
  const message = JSON.parse(data);
  
  if (message[1] === 'ownTrades') {
    console.log('귀하의 거래가 체결되었습니다:', message[0]);
  }
});

비공개 WebSocket 토큰은 15분 후에 만료됩니다. 운영 시스템을 위해 자동 토큰 갱신 및 재연결 로직을 구현하세요.

선물 거래 및 고급 기능

Kraken Futures는 고급 주문 유형 및 포트폴리오 마진 기능을 갖춘 파생상품 거래를 위한 별도의 인프라를 제공합니다.

선물 인증

선물은 현물 HMAC와는 다른 Bearer 토큰 인증을 사용합니다:

import requests
import hmac
import hashlib
import base64
import json

class KrakenFuturesAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = "https://futures.kraken.com/api/v3"
    
    def generate_signature(self, endpoint, method, body=None):
        nonce = str(int(time.time() * 1000))
        message = endpoint + method + nonce
        
        if body:
            message += json.dumps(body, separators=(',', ':'))
        
        signature = base64.b64encode(
            hmac.new(
                base64.b64decode(self.api_secret),
                message.encode(),
                hashlib.sha256
            ).digest()
        ).decode()
        
        return {
            'APIKey': self.api_key,
            'Nonce': nonce,
            'Authent': signature,
            'Content-Type': 'application/json'
        }
    
    def request(self, endpoint, method='GET', body=None):
        url = f"{self.base_url}{endpoint}"
        headers = self.generate_signature(endpoint, method, body)
        
        if method == 'GET':
            response = requests.get(url, headers=headers)
        else:
            response = requests.post(url, headers=headers, json=body)
        
        return response.json()

# 사용 예시
futures = KrakenFuturesAuth('FUTURES_API_KEY', 'FUTURES_SECRET')

선물 주문 체결

비트코인 무기한 선물에 지정가 주문 체결:

order = futures.request('/sendorder', 'POST', {
    'orderType': 'lmt',
    'side': 'buy',
    'size': 1,
    'limitPrice': 65000,
    'symbol': 'PI_XBTUSD'  # 무기한 역비트코인/USD
})

선물 심볼은 다른 규칙을 사용합니다:

PI_XBTUSD: 무기한 역비트코인/USD
PF_ETHUSD: 무기한 선형 이더리움/USD
FI_XBTUSD_250228: 2025년 2월 28일에 만기되는 고정 만기 선물

일괄 작업

선물 API는 일괄 주문 제출을 지원합니다:

batch = futures.request('/batchorder', 'POST', {
    'batchOrder': [
        {
            'order': 'send',
            'order_tag': '1',
            'orderType': 'lmt',
            'symbol': 'PI_XBTUSD',
            'side': 'buy',
            'size': 1,
            'limitPrice': 64000
        },
        {
            'order': 'send',
            'order_tag': '2',
            'orderType': 'lmt',
            'symbol': 'PI_XBTUSD',
            'side': 'sell',
            'size': 1,
            'limitPrice': 66000
        }
    ]
})

고급 주문 기능

트레일링 스탑 (Trailing Stops): 시장 움직임에 따라 스탑 가격 조정
이익 실현 / 손절매 (Take Profit / Stop Loss): 위험 관리를 위한 브라켓 주문
포스트 온리 (Post-Only): 주문이 유동성을 추가하도록 보장 (메이커 수수료)
리듀스 온리 (Reduce-Only): 포지션 증가 방지

데드맨 스위치

연결이 끊어지면 모든 주문 취소:

# 60초 타임아웃 설정
kraken.private_request('CancelAllOrdersAfter', {
    'timeout': 60
})

이는 서버 측 타이머를 생성합니다. 60초 이내에 하트비트를 보내지 않으면 Kraken이 모든 미체결 주문을 자동으로 취소합니다.

결론

Kraken의 API는 REST, WebSocket 및 전용 선물 인터페이스를 통해 암호화폐 시장에 대한 기관급 접근을 제공합니다. HMAC-SHA512 서명으로 인증하고, nonce 시퀀스를 신중하게 관리하며, 현물 거래에서 레버리지 선물까지 확장할 수 있습니다. 계층화된 속도 제한은 캐주얼한 포트폴리오 재조정부터 고빈도 시장 조성에 이르는 다양한 전략을 수용합니다.

인증 및 주문 체결을 테스트하려면 샌드박스 환경부터 시작하세요. nonce 충돌을 피하려면 각 거래 전략에 별도의 API 키를 사용하세요. 실시간 데이터를 위해 WebSocket 연결을 구현하고 위험 관리를 위해 데드맨 스위치를 구현하세요. 속도 제한 헤더를 모니터링하고 429 오류에 대해 지수 백오프를 구현하세요.

Kraken 엔드포인트를 테스트하든, 인증 서명을 디버깅하든, 여러 API 통합을 관리하든, 암호화폐 거래 애플리케이션을 구축할 때 Apidog를 사용하여 개발 워크플로우를 간소화하세요. Apidog는 시각적 API 테스트, 자동 문서 생성 및 팀 협업을 처리하므로 HMAC 서명과 씨름하는 대신 거래 로직에 집중할 수 있습니다.

button