timirey/xapi-php

PHP 封装 X-Trade Brokers (XTB) xStation5 交易 API 的包装器，支持通过套接字连接进行实时流和简单命令。

维护者

详细信息

github.com/timirey/xapi-php

源代码

问题

安装: 33

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

开放问题: 0

6.0.3 2024-07-30 13:21 UTC

Requires

  • php: ^8.3

Requires (Dev)

MIT de12315c21fb5eff40f7059a05f15f7e590c5819

  • Artiom Misiru <misiru.artiom.woop@gmail.com>

phpapiclientwrappertradingxAPIxtbxstationx-trade-brokers

This package is auto-updated.

Last update: 2024-09-30 13:41:50 UTC

README

XTB Online Investing

Tests Latest Stable Version Total Downloads License

这个 PHP 库为与 X-Trade Brokers (XTB) xStation5 交易 API 交互提供了一个全面且用户友好的界面。它支持广泛的函数，包括账户管理、交易执行、市场数据检索以及通过套接字进行实时流命令，使其成为开发者集成高级交易功能和实时市场数据到其应用程序的理想工具。

目录

安装

通过 Composer 安装包。

composer require timirey/xapi-php

用法

基本用法示例。

use Timirey\XApi\Client;
use Timirey\XApi\Enums\Host;
use Timirey\XApi\Responses\GetSymbolResponse;

$client = new Client(
    userId: 12345678,
    password: 'password',
    host: Host::DEMO,
    appName: 'My Test App'
);

/**
 * @var $response GetSymbolResponse
 */
$response = $client->getSymbol(
    symbol: 'EURUSD'
);

订阅流频道。

use Timirey\XApi\Client;
use Timirey\XApi\Enums\Host;
use Timirey\XApi\Responses\Data\TickStreamRecord;
use Timirey\XApi\Responses\FetchTickPricesResponse;

$client = new Client(
    userId: 12345678,
    password: 'password',
    host: Host::DEMO,
    appName: 'My Test App'
);

// Meant to be a daemon, run as separate process.
$client->fetchTickPrices(
    symbol: 'EURUSD',
    callback: static function (FetchTickPricesResponse $response): void {
        /**
         * @var TickStreamRecord $record
         */
        $record = $response->tickStreamRecord;
    },
    minArrivalTime: 100,
    maxLevel: 1
);

// Unreachable code.

可用命令

请求-回复命令在主连接套接字上执行。回复由主连接套接字发送。

login

登录 xStation5 API。

use Timirey\XApi\Responses\LoginResponse;
use Timirey\XApi\Client;

/** 
 * @var LoginResponse $response 
 * @var Client $client
 */
$response = $client->login(
    userId: 123456789, 
    password: 'password',
    appName: 'My App'
);

logout

从 xStation5 API 登出。

use Timirey\XApi\Responses\LogoutResponse;
use Timirey\XApi\Client;

/** 
 * @var LogoutResponse $response
 * @var Client $client
 */
$response = $client->logout();

可用流命令

fetchBalance (getBalance)

允许实时获取系统可用的实际账户指标值。

use Timirey\XApi\Responses\Data\BalanceStreamRecord;
use Timirey\XApi\Responses\FetchBalanceResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchBalance(
    callback: static function (FetchBalanceResponse $response): void {
        /**
         * @var BalanceStreamRecord $record
         */
        $record = $response->balanceStreamRecord;
    }
);

fetchCandles (getCandles)

订阅和取消订阅 API 图表蜡烛。每根蜡烛的间隔为 1 分钟。每分钟出现一根新的蜡烛。

use Timirey\XApi\Responses\Data\CandleStreamRecord;
use Timirey\XApi\Responses\FetchCandlesResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchCandles(
    symbol: 'EURUSD',
    callback: static function (FetchCandlesResponse $response): void {
        /**
         * @var CandleStreamRecord $record
         */
        $record = $response->candleStreamRecord;
    }
);

fetchKeepAlive (getKeepAlive)

订阅和取消订阅“保持活动状态”消息。API 每 3 秒发送一条新的“保持活动状态”消息。

use Timirey\XApi\Responses\Data\KeepAliveStreamRecord;
use Timirey\XApi\Responses\FetchKeepAliveResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchKeepAlive(
    callback: static function (FetchKeepAliveResponse $response): void {
        /**
         * @var KeepAliveStreamRecord $record
         */
        $record = $response->keepAliveStreamRecord;
    }
);

fetchNews (getNews)

订阅和取消订阅新闻。

use Timirey\XApi\Responses\Data\NewsStreamRecord;
use Timirey\XApi\Responses\FetchNewsResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchNews(
    callback: static function (FetchNewsResponse $response): void {
        /**
         * @var NewsStreamRecord $record
         */
        $record = $response->newsStreamRecord;
    }
);

fetchProfits (getProfits)

订阅和取消订阅利润。

use Timirey\XApi\Responses\Data\ProfitStreamRecord;
use Timirey\XApi\Responses\FetchProfitsResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchProfits(
    callback: static function (FetchProfitsResponse $response): void {
        /**
         * @var ProfitStreamRecord $record
         */
        $record = $response->profitStreamRecord;
    }
);

fetchTickPrices (getTickPrices)

建立报价订阅，允许实时获取系统中的相关信息。

use Timirey\XApi\Responses\Data\TickStreamRecord;
use Timirey\XApi\Responses\FetchTickPricesResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchTickPrices(
    symbol: 'EURUSD',
    callback: static function (FetchTickPricesResponse $response): void {
        /**
         * @var TickStreamRecord $record
         */
        $record = $response->tickStreamRecord;
    },
    maxLevel: 1,
    minArrivalTime: 200
);

fetchTrades (getTrades)

建立用户交易状态数据订阅，允许实时获取系统中的相关信息。

use Timirey\XApi\Responses\Data\TradeStreamRecord;
use Timirey\XApi\Responses\FetchTradesResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchTrades(
    callback: static function (FetchTradesResponse $response): void {
        /**
         * @var TradeStreamRecord $record
         */
        $record = $response->tradeStreamRecord;
    }
);

fetchTradeStatus (getTradeStatus)

允许实时获取已发送交易请求的状态，一旦系统中有相关信息即可获取。

use Timirey\XApi\Responses\Data\TradeStatusStreamRecord;
use Timirey\XApi\Responses\FetchTradeStatusResponse;
use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->fetchTradeStatus(
    callback: static function (FetchTradeStatusResponse $response): void {
        /**
         * @var TradeStatusStreamRecord $record
         */
        $record = $response->tradeStatusStreamRecord;
    }
);

pingStream (ping)

定期调用此函数足以刷新系统中所有组件的内部状态。

use Timirey\XApi\Client;

/**
 * @var Client $client
 */
$client->pingStream();

检索交易数据

getAllSymbols

检索所有符号的信息。

use Timirey\XApi\Responses\GetAllSymbolsResponse;
use Timirey\XApi\Client;

/** 
 * @var GetAllSymbolsResponse $response 
 * @var Client $client
 */
$response = $client->getAllSymbols();

getCalendar

返回包含市场事件日历。

use Timirey\XApi\Responses\GetCalendarResponse;
use Timirey\XApi\Client;

/** 
 * @var GetCalendarResponse $response 
 * @var Client $client
 */
$response = $client->getCalendar();

getChartLastRequest

返回从起始日期到当前时间的图表信息。

use Timirey\XApi\Responses\GetChartLastRequestResponse;
use Timirey\XApi\Client;
use Timirey\XApi\Payloads\Data\ChartLastInfoRecord;
use Timirey\XApi\Enums\Period;
use DateTime;

$chartLastInfoRecord = new ChartLastInfoRecord(
    period: Period::PERIOD_M1,
    start: new DateTime('-1 week'),
    symbol: 'EURUSD'
);

/** 
 * @var GetChartLastRequestResponse $response 
 * @var Client $client
 */
$response = $client->getChartLastRequest(
    chartLastInfoRecord: $chartLastInfoRecord
);

getChartRangeRequest

返回从起始日期到当前时间的图表信息。

use Timirey\XApi\Responses\GetChartRangeRequestResponse;
use Timirey\XApi\Client;
use Timirey\XApi\Payloads\Data\ChartRangeInfoRecord;
use Timirey\XApi\Enums\Period;
use DateTime;

$chartRangeInfoRecord = new ChartRangeInfoRecord(
    period: Period::PERIOD_H1,
    start: new DateTime('-1 month'),
    end: new DateTime(),
    symbol: 'EURUSD',
    ticks: 1000
);

/** 
 * @var GetChartRangeRequestResponse $response 
 * @var Client $client
 */
$response = $client->getChartRangeRequest(
    chartRangeInfoRecord: $chartRangeInfoRecord
);

getCommissionDef

返回佣金和汇率计算结果。

use Timirey\XApi\Responses\GetCommissionDefResponse;
use Timirey\XApi\Client;

/** 
 * @var GetCommissionDefResponse $response 
 * @var Client $client
 */
$response = $client->getCommissionDef(
    symbol: 'EURUSD',
    volume: 1.0
);

getCurrentUserData

返回账户货币和杠杆率信息。

use Timirey\XApi\Responses\GetCurrentUserDataResponse;
use Timirey\XApi\Client;

/** 
 * @var GetCurrentUserDataResponse $response 
 * @var Client $client
 */
$response = $client->getCurrentUserData();

getIbsHistory

返回给定时间范围内的IB数据。

use Timirey\XApi\Responses\GetIbsHistoryResponse;
use Timirey\XApi\Client;
use DateTime;

/** 
 * @var GetIbsHistoryResponse $response 
 * @var Client $client
 */
$response = $client->getIbsHistory(
    start: new DateTime('-1 month'),
    end: new DateTime()
);

getMarginLevel

返回各种账户指标。

use Timirey\XApi\Responses\GetMarginLevelResponse;
use Timirey\XApi\Client;

/** 
 * @var GetMarginLevelResponse $response 
 * @var Client $client
 */
$response = $client->getMarginLevel();

getMarginTrade

返回特定工具和数量的预期保证金。

use Timirey\XApi\Responses\GetMarginTradeResponse;
use Timirey\XApi\Client;

/** 
 * @var GetMarginTradeResponse $response 
 * @var Client $client
 */
$response = $client->getMarginTrade(
    symbol: 'EURPLN', 
    volume: 1.0
);

getNews

返回在指定时间段内从交易服务器发送的新闻。

use Timirey\XApi\Responses\GetNewsResponse;
use Timirey\XApi\Client;
use DateTime;

/** 
 * @var GetNewsResponse $response 
 * @var Client $client
 */
$response = $client->getNews(
    start: new DateTime('-1 month'), 
    end: new DateTime()
);

getProfitCalculation

计算给定交易数据的预估利润。

use Timirey\XApi\Responses\GetProfitCalculationResponse;
use Timirey\XApi\Client;
use Timirey\XApi\Enums\Cmd;

/** 
 * @var GetProfitCalculationResponse $response 
 * @var Client $client
 */
$response = $client->getProfitCalculation(
  closePrice: 1.3000, 
  cmd: Cmd::BUY, 
  openPrice: 1.2233, 
  symbol: 'EURPLN', 
  volume: 1.0
);

getServerTime

返回交易服务器上的当前时间。

use Timirey\XApi\Responses\GetServerTimeResponse;
use Timirey\XApi\Client;

/** 
 * @var GetServerTimeResponse $response 
 * @var Client $client
 */
$response = $client->getServerTime();

getStepRules

返回DMAs的步长规则列表。

use Timirey\XApi\Responses\GetStepRulesResponse;
use Timirey\XApi\Client;

/** 
 * @var GetStepRulesResponse $response 
 * @var Client $client
 */
$response = $client->getStepRules();

getSymbol

检索特定符号的信息。

use Timirey\XApi\Responses\GetSymbolResponse;
use Timirey\XApi\Client;

/** 
 * @var GetSymbolResponse $response 
 * @var Client $client
 */
$response = $client->getSymbol(
    symbol: EURUSD
);

getTickPrices

返回给定符号的当前报价数组。

use Timirey\XApi\Responses\GetTickPricesResponse;
use Timirey\XApi\Enums\Level;
use Timirey\XApi\Client;
use DateTime;

/**
 * @var GetTickPricesResponse $response
 * @var Client $client
 */
$response = $client->getTickPrices(
    level: Level::BASE, 
    symbols: ['EURPLN', 'AGO.PL'], 
    timestamp: new DateTime()
);

getTradeRecords

返回orders参数中列出的交易数组。

use Timirey\XApi\Responses\GetTradeRecordsResponse;
use Timirey\XApi\Client;

/** 
 * @var GetTradeRecordsResponse $response 
 * @var Client $client
 */
$response = $client->getTradeRecords(
    orders: [7489839, 7489841]
);

getTrades

返回用户的交易数组。

use Timirey\XApi\Responses\GetTradesResponse;
use Timirey\XApi\Client;

/** 
 * @var GetTradesResponse $response 
 * @var Client $client
 */
$response = $client->getTrades(
    openedOnly: true
);

getTradesHistory

返回在指定时间段内关闭的用户交易数组。

use Timirey\XApi\Responses\GetTradesHistoryResponse;
use Timirey\XApi\Client;
use DateTime;

/** 
 * @var GetTradesHistoryResponse $response 
 * @var Client $client
 */
$response = $client->getTradesHistory(
    start: new DateTime('last month'), 
    end: new DateTime()
);

getTradingHours

返回报价和交易时间。

use Timirey\XApi\Responses\GetTradingHoursResponse;
use Timirey\XApi\Client;

/** 
 * @var GetTradingHoursResponse $response 
 * @var Client $client
 */
$response = $client->getTradingHours(
    symbols: ['EURPLN', 'AGO.PL']
);

getVersion

返回当前API版本。

use Timirey\XApi\Responses\GetVersionResponse;
use Timirey\XApi\Client;

/** 
 * @var GetVersionResponse $response 
 * @var Client $client
 */
$response = $client->getVersion();

ping

定期调用此函数足以刷新系统中所有组件的内部状态。

use Timirey\XApi\Responses\PingResponse;
use Timirey\XApi\Client;

/** 
 * @var PingResponse $response 
 * @var Client $client
 */
$response = $client->ping();

tradeTransaction

启动交易事务。

use Timirey\XApi\Responses\TradeTransactionResponse;
use Timirey\XApi\Payloads\Data\TradeTransInfo;
use Timirey\XApi\Client;

$tradeTransInfo = new TradeTransInfo(
    cmd: Cmd::BUY,
    customComment: 'Test trade',
    expiration: new DateTime(),
    offset: 0,
    order: 0,
    price: 1.12345,
    sl: 1.12000,
    symbol: 'EURUSD',
    tp: 1.12500,
    type: Type::OPEN,
    volume: 1.0
);

/** 
 * @var TradeTransactionResponse $response 
 * @var Client $client
 */
$response = $client->tradeTransaction(
    tradeTransInfo: $tradeTransInfo
);

tradeTransactionStatus

返回当前事务状态。

use Timirey\XApi\Responses\TradeTransactionStatusResponse;
use Timirey\XApi\Client;

/** 
 * @var TradeTransactionStatusResponse $response 
 * @var Client $client
 */
$response = $client->tradeTransactionStatus(
    order: 123456
);

错误处理

处理请求错误的自定义异常。

ErrorResponseException

当API返回错误（例如，密码无效）时抛出。提供错误代码和描述。

use Timirey\XApi\Exceptions\ResponseException;
use Timirey\XApi\Enums\Host;
use Timirey\XApi\Client;

/** 
 * @var Client $client 
 */
$client = new Client(
    userId: 123456789, 
    password: 'invalidPassword', 
    host: Host::DEMO
);

try {
    $client->getVersion();
} catch (ErrorResponseException $e) {
    echo ($e->getErrorCode()); // 'BE005'
    echo ($e->getErrorDescr()); // 'userPasswordCheck: Invalid login or password.'
}

所有错误代码和描述都可以在官方文档中找到。

InvalidResponseException

当请求失败且API未返回适当的错误响应时抛出（例如，无效或不完整的响应）。

InvalidPayloadException

当由于某种原因有效负载无效时抛出（通常是xApi的无效响应）。

SocketException

当由于某种原因套接字连接/读取/写入失败时抛出。

测试

此包使用PestPHP框架进行测试。

./vendor/bin/pest

许可证

此库是开源软件，许可协议为MIT许可。

参考

有关更详细的文档，请参阅XTB xStation5 交易API文档。