XTB API 更新 sgcWebSockets

2026年3月9日 · 功能

XTB xStation5 交易 API 集成——Delphi 实现

XTB 是欧洲领先的在线交易平台之一，通过其 xStation5 平台提供外汇、指数、大宗商品、股票和加密货币的交易渠道。TsgcWSAPI_XTB 组件通过单一 WebSocket 连接为 xStation5 API 提供完整的 Delphi 集成，涵盖身份验证、市场数据获取、账户管理、交易执行以及实时流式订阅。本文将逐一讲解所有可用方法，并演示如何在几分钟内快速上手。

架构概览

与许多将功能分散在 REST 端点和 WebSocket 通道之间的加密货币交易所不同，XTB xStation5 API 完全通过单一 WebSocket 连接运行。每个请求——从获取品种列表到下达交易——都在同一套接字上以 JSON 消息的形式发送和接收。第二个流式套接字由系统自动管理，用于实时订阅（余额、K 线、报价、交易等）。

TsgcWSAPI_XTB 组件为您抽象了所有这些细节。您只需分配一个 TsgcWebSocketClient，配置您的凭据，激活客户端，然后调用 GetAllSymbols 或 SubscribeTickPrices 等高级方法即可。

身份验证

当 WebSocket 客户端连接时，系统使用您在 XTB 属性组中设置的凭据自动处理身份验证。如有需要，您也可以显式调用这些方法。

方法	描述
`Login`	使用 UserId 和 Password 向 xStation5 服务器进行身份验证。连接时自动调用。
`Logout`	终止已验证的会话并从服务器断开连接。

市场数据方法

这些方法从 xStation5 服务器获取品种信息、价格、图表、新闻和交易时段。所有调用均通过 WebSocket 连接以请求/响应方式进行。

方法	描述
`GetAllSymbols`	返回平台上所有可用品种的列表。
`GetSymbol`	返回特定品种的详细信息。
`GetTickPrices`	返回指定品种的当前报价（买入价/卖出价）。
`GetTradingHours`	返回指定品种的交易时段。
`GetCalendar`	返回即将发生的经济事件日历。
`GetChartLastRequest`	返回从指定时间戳至当前时间的图表 K 线数据。
`GetChartRangeRequest`	返回指定日期范围内的图表 K 线数据。
`GetNews`	返回 XTB 交易平台的新闻资讯。
`GetStepRules`	返回成交量计算的步进规则。
`GetServerTime`	返回当前服务器时间。
`GetVersion`	返回 API 版本号。

账户方法

账户方法允许您在不离开 WebSocket 会话的情况下查看用户资料、保证金水平和盈利计算。

方法	描述
`GetCurrentUserData`	返回当前登录用户的信息（姓名、货币、杠杆等）。
`GetMarginLevel`	返回当前账户的保证金水平、净值和余额。
`GetMarginTrade`	计算给定品种和手数的预期保证金。
`GetIbsHistory`	返回介绍经纪人（IB）的佣金历史记录。
`GetProfitCalculation`	计算给定交易场景的预估盈利。

交易方法

这些方法涵盖从读取持仓和历史仓位到下达和监控交易订单的全部操作。

方法	描述
`GetTrades`	返回当前持仓列表。传入 `True` 仅包含已开仓位。
`GetTradesHistory`	返回指定时间范围内的已平仓交易。
`GetTradeRecords`	返回指定订单号的交易记录。
`TradeTransaction`	执行交易操作（开仓、平仓、修改或删除订单）。
`TradeTransactionStatus`	查询之前提交的交易操作的当前状态。

实时流式订阅

流式方法在专用流式连接上打开实时数据通道。每个订阅都有相应的取消订阅方法来停止接收更新。

订阅	取消订阅	描述
`SubscribeBalance`	`UnSubscribeBalance`	实时余额和净值更新。
`SubscribeCandles`	`UnSubscribeCandles`	品种的实时 K 线/图表更新。
`SubscribeKeepAlive`	`UnSubscribeKeepAlive`	周期性保活心跳消息。
`SubscribeNews`	`UnSubscribeNews`	平台实时新闻推送。
`SubscribeProfits`	`UnSubscribeProfits`	持仓的实时盈亏更新。
`SubscribeTickPrices`	`UnSubscribeTickPrices`	品种的实时买卖报价。
`SubscribeTrades`	`UnSubscribeTrades`	交易开仓、平仓或修改时的实时更新。
`SubscribeTradeStatus`	`UnSubscribeTradeStatus`	交易操作状态的实时变化。
`SubscribePing`	—	订阅流式 ping 以保持连接活跃（无需取消订阅）。

注意：流式订阅需要先成功登录。流式会话 ID 在身份验证过程中自动获取。

工具方法

方法	描述
`Ping`	向服务器发送 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` 连接实盘生产服务器。

提示与注意事项

演示账户与实盘账户

始终使用 XTB.Demo := True 进行开发和测试。演示服务器使用与生产环境相同的 API 接口，但连接到带有虚拟资金的沙箱环境。仅在准备好进行实盘交易时才切换为 False。

连接保活

XTB 服务器会在超时后断开空闲会话。使用 SubscribePing 或定期调用 Ping 来保持连接活跃。流式连接上的 SubscribeKeepAlive 方法具有类似用途。

单连接架构

与具有独立 REST 端点的交易所不同，XTB 通过 WebSocket 消息路由每个命令。这简化了组件架构：您只需一个 TsgcWebSocketClient 和一个 TsgcWSAPI_XTB — 无需额外的 HTTP 组件。

错误处理

如果请求失败，服务器返回带有错误代码和描述的 JSON 错误响应。在响应事件中通过检查 status 字段来处理这些情况。常见问题包括无效凭据、会话过期以及过多请求导致的速率限制。

速率限制：XTB API 强制执行每秒请求限制。避免在紧密循环中发送突发请求。适当间隔调用，或对频繁更新的数据使用流式订阅。

目录