XTB는 유럽 최고의 온라인 트레이딩 플랫폼 중 하나로, xStation5 플랫폼을 통해 외환, 지수, 원자재, 주식, 암호화폐에 접근할 수 있어요. TsgcWSAPI_XTB 컴포넌트는 단일 WebSocket 연결을 통해 xStation5 API와의 완전한 Delphi 통합을 제공해요. 인증, 시장 데이터 조회, 계정 관리, 거래 실행, 실시간 스트리밍 구독을 지원해요. 이 글은 사용 가능한 모든 메서드를 설명하고 몇 분 안에 시작하는 방법을 보여줘요.
목차
아키텍처 개요
많은 암호화폐 거래소가 REST 엔드포인트와 WebSocket 채널로 기능을 분리하는 것과 달리, XTB xStation5 API는 단일 WebSocket 연결로만 작동해요. 심볼 목록 조회부터 거래 실행까지 모든 요청이 동일한 소켓에서 JSON 메시지로 송수신돼요. 실시간 구독(잔고, 캔들, 틱, 거래 등)을 위한 두 번째 스트리밍 소켓이 자동으로 관리돼요.
TsgcWSAPI_XTB 컴포넌트가 이 모든 것을 추상화해요. TsgcWebSocketClient를 할당하고 자격 증명을 설정한 후 클라이언트를 활성화하면 GetAllSymbols나 SubscribeTickPrices 같은 고수준 메서드를 호출할 수 있어요.
인증
WebSocket 클라이언트가 연결될 때 XTB 속성 그룹에 설정한 자격 증명을 사용해 인증이 자동으로 처리돼요. 필요한 경우 이 메서드를 명시적으로 호출할 수도 있어요.
| 메서드 | 설명 |
|---|---|
Login |
UserId와 Password를 사용해 xStation5 서버로 인증해요. 연결 시 자동으로 호출돼요. |
Logout |
인증된 세션을 종료하고 서버에서 연결을 끊어요. |
시장 데이터 메서드
이 메서드들은 xStation5 서버에서 종목 정보, 가격, 차트, 뉴스, 거래 시간을 조회해요. 모든 호출은 WebSocket 연결을 통한 요청/응답 방식이에요.
| 메서드 | 설명 |
|---|---|
GetAllSymbols |
플랫폼에서 사용 가능한 모든 종목 목록을 반환해요. |
GetSymbol |
특정 심볼에 대한 상세 정보를 반환해요. |
GetTickPrices |
지정된 심볼의 현재 틱 가격(매수/매도)을 반환해요. |
GetTradingHours |
주어진 종목의 거래 시간을 반환해요. |
GetCalendar |
예정된 이벤트의 경제 달력을 반환해요. |
GetChartLastRequest |
주어진 타임스탬프부터 현재까지의 차트 캔들 데이터를 반환해요. |
GetChartRangeRequest |
특정 날짜 범위의 차트 캔들 데이터를 반환해요. |
GetNews |
XTB 트레이딩 플랫폼의 뉴스 토픽을 반환해요. |
GetStepRules |
볼륨 계산을 위한 단계 규칙을 반환해요. |
GetServerTime |
현재 서버 시간을 반환해요. |
GetVersion |
API 버전 번호를 반환해요. |
계정 메서드
계정 메서드를 사용하면 WebSocket 세션을 유지하면서 사용자 프로필, 마진 수준, 수익 계산을 확인할 수 있어요.
| 메서드 | 설명 |
|---|---|
GetCurrentUserData |
현재 로그인된 사용자 정보(이름, 통화, 레버리지 등)를 반환해요. |
GetMarginLevel |
현재 계정 마진 수준, 자본, 잔고를 반환해요. |
GetMarginTrade |
주어진 종목과 볼륨에 대한 예상 마진을 계산해요. |
GetIbsHistory |
소개 브로커(IB) 수수료 내역을 반환해요. |
GetProfitCalculation |
주어진 거래 시나리오의 예상 수익을 계산해요. |
트레이딩 메서드
이 메서드들은 미결 포지션과 거래 내역 조회부터 거래 실행 및 모니터링까지 모든 것을 다루어요.
| 메서드 | 설명 |
|---|---|
GetTrades |
현재 미결 거래 목록을 반환해요. True를 전달하면 미결 포지션만 포함해요. |
GetTradesHistory |
지정된 시간 범위 내에서 완료된 거래를 반환해요. |
GetTradeRecords |
지정된 주문 번호의 거래 레코드를 반환해요. |
TradeTransaction |
거래 트랜잭션을 실행해요(주문 열기, 닫기, 수정 또는 삭제). |
TradeTransactionStatus |
이전에 제출된 거래 트랜잭션의 현재 상태를 확인해요. |
스트리밍 구독
스트리밍 메서드는 전용 스트리밍 연결에서 실시간 데이터 채널을 열어요. 각 구독에는 업데이트 수신을 중지하는 대응 구독 해제 메서드가 있어요.
| 구독 | 구독 해제 | 설명 |
|---|---|---|
SubscribeBalance |
UnSubscribeBalance |
실시간 잔고 및 자본 업데이트예요. |
SubscribeCandles |
UnSubscribeCandles |
심볼의 실시간 캔들/차트 업데이트예요. |
SubscribeKeepAlive |
UnSubscribeKeepAlive |
주기적인 연결 유지 하트비트 메시지예요. |
SubscribeNews |
UnSubscribeNews |
플랫폼의 실시간 뉴스 피드예요. |
SubscribeProfits |
UnSubscribeProfits |
미결 포지션의 실시간 손익 업데이트예요. |
SubscribeTickPrices |
UnSubscribeTickPrices |
심볼의 실시간 매수/매도 틱 가격이에요. |
SubscribeTrades |
UnSubscribeTrades |
거래가 열리거나 닫히거나 수정될 때 실시간 업데이트예요. |
SubscribeTradeStatus |
UnSubscribeTradeStatus |
실시간 거래 트랜잭션 상태 변경이에요. |
SubscribePing |
— | 연결을 유지하기 위한 스트리밍 핑을 구독해요(구독 해제 불필요). |
유틸리티 메서드
| 메서드 | 설명 |
|---|---|
Ping |
서버에 핑을 보내 연결이 살아 있는지 확인하고 타임아웃을 방지해요. |
시작하기 — 코드 예제
다음 예제는 XTB 데모 서버에 연결을 생성하고 인증 후 심볼과 사용자 데이터를 조회하며, 실시간 틱 가격과 잔고 업데이트를 구독하고 미결 거래를 가져와요.
var
oClient: TsgcWebSocketClient;
oXTB: TsgcWSAPI_XTB;
begin
// Create the WebSocket client
oClient := TsgcWebSocketClient.Create(nil);
// Create the XTB API component
oXTB := TsgcWSAPI_XTB.Create(nil);
oXTB.Client := oClient;
// Configure credentials
oXTB.XTB.UserId := 'your_user_id';
oXTB.XTB.Password := 'your_password';
oXTB.XTB.Demo := True;
// Connect and authenticate
oClient.Active := True;
// After the login event fires, call API methods:
oXTB.GetAllSymbols;
oXTB.GetCurrentUserData;
// Subscribe to real-time tick prices for EURUSD
oXTB.SubscribeTickPrices('EURUSD', 0, 0);
// Subscribe to balance updates
oXTB.SubscribeBalance;
// Get all open trades
oXTB.GetTrades(False);
end;응답 처리
모든 응답은 컴포넌트 이벤트를 통해 비동기로 도착해요. OnXTBResponse 및 OnXTBStreamingResponse 같은 이벤트에 핸들러를 할당해 반환된 JSON 데이터를 처리하세요. 각 응답에는 명령 식별자가 포함되어 있어 적절한 처리 로직으로 라우팅할 수 있어요.
설정 참조
모든 설정은 TsgcWSAPI_XTB 컴포넌트의 XTB 속성 아래에 그룹화되어 있어요.
| 속성 | 유형 | 설명 |
|---|---|---|
XTB.UserId |
String | XTB 계정 사용자 ID예요. |
XTB.Password |
String | XTB 계정 비밀번호예요. |
XTB.Demo |
Boolean | 데모 서버에 연결하려면 True로 설정하고, 라이브 프로덕션 서버에는 False로 설정해요. |
팁과 참고 사항
데모 vs. 라이브
항상 XTB.Demo := True로 개발하고 테스트하세요. 데모 서버는 프로덕션과 동일한 API 표면을 사용하지만 가상 자금이 있는 샌드박스 환경에 연결해요. 실거래 준비가 됐을 때만 False로 전환하세요.
연결 유지
XTB 서버는 타임아웃 기간 후 유휴 세션의 연결을 끊어요. 연결을 유지하려면 SubscribePing을 사용하거나 주기적으로 Ping을 호출하세요. 스트리밍 연결의 SubscribeKeepAlive 메서드도 비슷한 역할을 해요.
단일 연결 아키텍처
별도의 REST 엔드포인트가 있는 거래소와 달리 XTB는 모든 명령을 WebSocket 메시지를 통해 라우팅해요. 이로 인해 컴포넌트 아키텍처가 단순해져요. TsgcWebSocketClient와 TsgcWSAPI_XTB만 필요하며 추가 HTTP 컴포넌트는 필요하지 않아요.
오류 처리
요청이 실패하면 서버는 오류 코드와 설명이 담긴 JSON 오류 응답을 반환해요. 응답 이벤트에서 status 필드를 확인해 처리하세요. 일반적인 문제로는 잘못된 자격 증명, 만료된 세션, 과도한 요청으로 인한 속도 제한이 있어요.