进阶版 API 文档说明
本页面向高端技术专家开放。若你需要在 EA 中深度对接 TraderEdgAIFactor.dll,需要每个 API 的完整入参、出参及参数说明,以及可直接复用的 MQ4/MQ5 代码片段,请以本页为准。
进阶版文档的价值与作用:
- 减少对接歧义:每个 API 均给出入参、出参、参数含义与取值范围,避免因理解偏差导致调用错误。
- 提供详细代码片段:MQ4 与 MQ5 双平台示例、注释与常见坑(如数组顺序、调用顺序、返回值检查),便于直接集成、减少反复试错与客服咨询。
- 仅展示对接用 API:不涉及内部实现与框架,只列出你实际会调用的接口、参数与用法。
简单对接(极简代码与场景说明)请见 API 文档(简单版)。
类型与常量
对接时用到的因子 ID、Action 常量及标准信号结构(MQ4 中结构体名可能为 TEAStandardSignalData,以头文件为准)。
因子 ID(统一接口使用)
| 常量 | 值 | 说明 |
|---|---|---|
TEA_FACTOR_ENTROPY_HEDGE | 0 | EntropyHedge 熵场与对冲矩阵 |
TEA_FACTOR_TREND_PENALTY | 1 | TrendPenalty 趋势与惩罚 |
TEA_FACTOR_HEDGE_REGIME | 2 | HedgeRegime 趋势·震荡·刹车 |
TEA_FACTOR_TREND_STRENGTH_BRAKE | 3 | TrendStrengthBrake 多周期 R²·刹车强度 |
标准信号结构 TEAStandardSignal(MQ4 中为 TEAStandardSignalData)
Action 枚举
| 常量 | 值 |
|---|---|
TEA_ACTION_FLAT | 0 |
TEA_ACTION_LONG | 1 |
TEA_ACTION_SHORT | 2 |
标准因子 API (TEA_*)
以下为对接时实际调用的 API:创建因子、传入 K 线、取回方向/动作/置信度等。handle 在 MQ4 中为 int;数组顺序 下标 0 = 最旧一根 K 线,size-1 = 最新;必须先调用 Process 且返回 1,再调用 Get* 取信号,否则结果未定义。
| 入参 | 类型 | 说明 |
|---|---|---|
| factorId | int | 因子 ID:0=EntropyHedge,1=TrendPenalty,2=HedgeRegime,3=TrendStrengthBrake。见上方类型与常量。 |
| 返回值 | int | 成功返回非 0 句柄,失败返回 0。MQ4 用 int 接收;OnInit 中若为 0 应返回 INIT_FAILED。 |
|---|
| 入参 | 类型 | 说明 |
|---|---|---|
| handle | int | TEA_FactorCreate 返回的句柄。OnDeinit 中必须调用,且仅对非 0 句柄调用,避免重复释放。 |
| 入参 | 类型 | 说明 |
|---|---|---|
| handle | int | 因子句柄,非 0。 |
| opens, highs, lows, closes, volumes | double[] | 开盘、最高、最低、收盘、成交量数组。顺序:下标 0 = 最旧 K 线,size-1 = 最新;与 MT 的 CopyOpen 等顺序一致(时间升序)。 |
| size | int | 数组长度,至少 50,建议 200。五组数组长度必须一致。 |
| 返回值 | int | 1=成功,0=失败。仅当返回 1 时方可调用 GetDirection/GetAction 等;否则不要读取信号。 |
|---|
| 入参 | 说明 |
|---|---|
| handle | 同上,且必须在本 tick 已成功调用过 TEA_FactorProcess(handle, ...) 且返回 1。 |
| 返回值 | 说明 |
|---|---|
| GetDirection | double:-1.0=偏空,0=中性,+1.0=偏多。用于过滤或仓位方向。 |
| GetAction | int:0=FLAT(观望),1=LONG(做多),2=SHORT(做空)。直接用于开平仓判断。 |
| GetRegime | int:1=趋势,2=震荡,-1=高风险。可用于减仓或刹车逻辑。 |
其余 Get* API(信号与风控)
以下 API 与 GetDirection/GetAction/GetRegime 调用约定相同:必须先在本 tick 调用 TEA_FactorProcess 且返回 1,再调用下列 Get*;否则返回值未定义。入参均为 int handle(因子句柄),下表仅列出返回值类型与含义。
| API | 签名 | 返回值 / 说明 |
|---|---|---|
TEA_FactorGetConfidence | double TEA_FactorGetConfidence(int handle); | double,0~1。信号置信度,常用于过滤:仅当 confidence > 某阈值时开仓,或传入削单接口 TEA_ReductionRecommend 的 confidence 参数。 |
TEA_FactorGetStrength | double TEA_FactorGetStrength(int handle); | double,0~1。信号强度,可用于仓位权重或过滤弱信号。 |
TEA_FactorGetScore | double TEA_FactorGetScore(int handle); | double,0~1。综合评分,与标准信号结构中的 score 一致,用于排序或过滤。 |
TEA_FactorIsValid | int TEA_FactorIsValid(int handle); | int:1=有效,0=无效。深度集成时建议必读:仅在返回 1 时依据 Action/Direction 开仓,否则本 tick 不交易,避免在无效信号上下单。 |
TEA_FactorGetAccuracyScore | int TEA_FactorGetAccuracyScore(int handle); | int,0~100。准确度/质量分,与标准信号结构 accuracy_score 一致,可用于多因子加权或风控阈值。 |
TEA_FactorGetStopLoss | double TEA_FactorGetStopLoss(int handle); | double。因子建议的止损价;0 表示本因子不提供止损,需自行计算或使用其他逻辑。 |
TEA_FactorGetTakeProfit | double TEA_FactorGetTakeProfit(int handle); | double。因子建议的止盈价;0 表示本因子不提供止盈。 |
TEA_FactorGetBrake | int TEA_FactorGetBrake(int handle); | int:0 或 1。仅 HedgeRegime 因子:刹车标志,1=当前建议刹车(减仓/观望),可用于对冲 EA 的减仓或暂停加仓逻辑。 |
TEA_FactorGetATR | double TEA_FactorGetATR(int handle); | double。仅 HedgeRegime 因子:内部使用的 ATR 值,可用于与自算 ATR 对比或风控参考。 |
TEA_FactorGetBrakeStrength | double TEA_FactorGetBrakeStrength(int handle); | double,0~1。仅 TrendStrengthBrake 因子:刹车强度,用于多周期 R²·刹车类策略的仓位或风控。 |
常见用法:开仓前可组合判断,例如 if (TEA_FactorProcess(g_h, ...) == 1 && TEA_FactorIsValid(g_h) == 1 && TEA_FactorGetConfidence(g_h) >= 0.6) { ... } 再根据 GetAction 下单;若使用因子建议止损止盈,则读取 GetStopLoss/GetTakeProfit,为 0 时忽略。
MQ4 对接代码片段(可直接复用)
#include <TraderEdgAIFactor.mqh>
int g_h = 0; // 因子句柄,全局保存
int OnInit() {
g_h = TEA_FactorCreate(2); // 2=HedgeRegime,可选 0/1/3
if (g_h == 0) { Print("TEA: 因子创建失败"); return INIT_FAILED; }
return INIT_SUCCEEDED;
}
void OnDeinit(int reason) {
if (g_h != 0) { TEA_FactorDestroy(g_h); g_h = 0; } // 仅对非 0 释放
}
void OnTick() {
if (g_h == 0) return;
// 准备 K 线:下标 0=最旧,n-1=最新,与 iOpen(..., bar) 顺序一致
double o[], h[], l[], c[], v[];
int n = 200;
ArrayResize(o, n); ArrayResize(h, n); ArrayResize(l, n);
ArrayResize(c, n); ArrayResize(v, n);
for (int i = 0; i < n; i++) {
int bar = n - 1 - i;
o[i] = iOpen(Symbol(), PERIOD_CURRENT, bar);
h[i] = iHigh(Symbol(), PERIOD_CURRENT, bar);
l[i] = iLow(Symbol(), PERIOD_CURRENT, bar);
c[i] = iClose(Symbol(), PERIOD_CURRENT, bar);
v[i] = (double)iVolume(Symbol(), PERIOD_CURRENT, bar);
}
if (TEA_FactorProcess(g_h, o, h, l, c, v, n) != 1) return; // 失败则不读信号
double dir = TEA_FactorGetDirection(g_h);
int act = TEA_FactorGetAction(g_h);
int regime = TEA_FactorGetRegime(g_h);
// 使用 dir / act / regime 做开平仓逻辑
}
MQ5 对接代码片段(可直接复用)
#include <TraderEdgAIFactor.mqh>
int g_h = 0;
int OnInit() {
g_h = TEA_FactorCreate(TEA_FACTOR_HEDGE_REGIME); // 2
if (g_h == 0) { Print("TEA: 因子创建失败"); return INIT_FAILED; }
return INIT_SUCCEEDED;
}
void OnDeinit(const int reason) {
if (g_h != 0) { TEA_FactorDestroy(g_h); g_h = 0; }
}
void OnTick() {
if (g_h == 0) return;
MqlRates rates[];
int n = 200;
if (CopyRates(_Symbol, PERIOD_CURRENT, 0, n, rates) != n) return; // 0=最旧,n-1=最新
double o[], h[], l[], c[], v[];
ArrayResize(o, n); ArrayResize(h, n); ArrayResize(l, n); ArrayResize(c, n); ArrayResize(v, n);
for (int i = 0; i < n; i++) {
o[i] = rates[i].open; h[i] = rates[i].high;
l[i] = rates[i].low; c[i] = rates[i].close;
v[i] = (double)rates[i].tick_volume;
}
if (TEA_FactorProcess(g_h, o, h, l, c, v, n) != 1) return;
double dir = TEA_FactorGetDirection(g_h);
int act = TEA_FactorGetAction(g_h);
int regime = TEA_FactorGetRegime(g_h);
}
常见问题:① 数组顺序反了会导致信号错误,务必 0=最旧;传入 Process 的 K 线数组不要使用 ArraySetAsSeries(true),否则顺序会反。② Process 返回 0 时不要调用 Get*。③ handle 为 0 时不要调用任何接口。④ OnDeinit 里只对非 0 handle 调用 Destroy。
削单 API · TEA_ReductionRecommend
无状态接口:每次传入多空两侧持仓的盈亏、手数、开仓时间等数组及少量控制参数,返回本 tick 是否建议削单及削哪一侧、先平盈利再平亏损。适合对冲/马丁 EA 的减仓决策。详见 算法因子库 ReductionAdvisor。
入参说明
| 参数 | 类型 | 说明 |
|---|---|---|
| profit_buy[], lots_buy[], open_time_buy[] | 数组 | 多侧每笔持仓的浮动盈亏、手数、开仓时间(Unix 或 MQL 时间)。必须按开仓时间升序排列。 |
| count_buy | int | 多侧持仓笔数,与上面三个数组长度一致。 |
| profit_sell[], lots_sell[], open_time_sell[] | 数组 | 空侧同上,按开仓时间升序。 |
| count_sell | int | 空侧持仓笔数。 |
| regime | int | 市场状态:1=趋势,2=震荡,-1=高风险。可与 TEA_FactorGetRegime 一致。 |
| confidence | double | 置信度 0~1。 |
| target_net | double | 目标净利,可传 0。 |
| max_tail_count | int | 尾端(亏损段)最多保留笔数。 |
| min_margin_base | double | 最小保证金基数,可传 0。 |
| allow_cross_side | int | 是否允许跨侧削单:0=否,1=是。 |
| risk_mode | int | 风控模式,见头文件常量。 |
出参说明(DLL 写回,调用前需声明变量)
| 参数 | 类型 | 说明 |
|---|---|---|
| out_action | int & | 1=单侧削多,2=单侧削空,3=跨侧削单。 |
| out_side | int & | 亏损侧。 |
| out_loss_index | int & | 亏损单索引。 |
| out_profit_start_index | int & | 盈利段起始索引(先平这部分)。 |
| out_profit_count | int & | 盈利段笔数。执行顺序:先平盈利段 [start_index, start_index+count),再平亏损。 |
| out_segment_side, out_cross_side | int & | 段侧、是否跨侧,见头文件。 |
| out_net_profit, out_reduction_potential, out_estimated_float_reduction | double & | 净利、削单潜能等,按需使用。 |
| out_strategy_used | int & | 本次使用的策略标识。 |
| 返回值 | int | 1=本 tick 有削单推荐,可按 out_* 执行平仓;0=无推荐。 |
|---|
MQ4 对接代码片段(声明出参变量后调用)
// 1. 准备多空两侧数组:按开仓时间升序填充 profit_buy[], lots_buy[], open_time_buy[] 与 sell 侧
// 2. 取得 regime、confidence(例如从 TEA_FactorGetRegime/GetConfidence)
int regime = 1;
double confidence = 0.7;
// 3. 声明所有出参变量(MQ4 中通过引用传回)
int out_act, out_side, out_loss_idx, out_profit_start, out_profit_cnt;
int out_seg_side, out_cross_side, out_strategy;
double out_net, out_potential, out_float_red;
// 4. 调用(数组与 count 必须对应)
int hasRec = TEA_ReductionRecommend(
profit_buy, lots_buy, open_time_buy, count_buy,
profit_sell, lots_sell, open_time_sell, count_sell,
regime, confidence, 0.0, 3, 0.0, 1, 0,
out_act, out_side, out_loss_idx, out_profit_start, out_profit_cnt,
out_seg_side, out_cross_side,
out_net, out_potential, out_float_red, out_strategy
);
if (hasRec == 1) {
// 有推荐:先平盈利段(从 out_profit_start 起共 out_profit_cnt 笔),再平亏损单
// 根据 out_act/out_side 判断是单侧还是跨侧
}
常见问题:① 多空数组必须按开仓时间升序,否则推荐结果可能错误。② 出参必须提前声明变量,MQ4 中通过引用传回。③ 先平盈利再平亏损。④ allow_cross_side=0 时不会返回跨侧建议。完整签名以 TraderEdgAIFactor.mqh 为准。
R² API · TEA_RSquared / TEA_RSquaredEx
无状态接口:传入收盘价数组与长度,返回 0~1 的趋势强度 R²。用于替代手写 R²,数值稳定、抗异常值。详见 算法因子库 RSquared。
| 入参 | 类型 | 说明 |
|---|---|---|
| closes[] | double[] | 收盘价数组。下标 0 = 最旧 K 线,count-1 = 最新(时间升序)。 |
| count | int | 数组长度,即计算 R² 的 K 线根数。建议 2~512;count<2 时返回 0。 |
| 返回值 | double | 0~1,越接近 1 趋势越强,接近 0 表示无明显趋势。 |
|---|
| 入参 | 类型 | 说明 |
|---|---|---|
| closes[], count | 同上 | 同上。 |
| mode | int | 0=Pearson(数值稳定),1=Theil-Sen 稳健,2=指数加权。 |
| out_slope | double & | 可选,非 NULL 时写回拟合斜率。 |
| 返回值 | double | 0~1,同上。 |
|---|
MQ4 对接代码片段
double closes[];
int n = 100;
ArrayResize(closes, n);
CopyClose(Symbol(), PERIOD_CURRENT, 0, n, closes); // 0=最旧,n-1=最新
double r2 = TEA_RSquared(closes, n);
// r2 在 0~1,可用于过滤或仓位权重
MQ5 对接代码片段
double closes[];
int n = 100;
if (CopyClose(_Symbol, PERIOD_CURRENT, 0, n, closes) != n) return;
double r2 = TEA_RSquared(closes, n);
常见问题:① 数组顺序必须 0=最旧,否则 R² 含义错误。② count<2 返回 0。③ 需 Theil-Sen 或指数加权时用 TEA_RSquaredEx(closes, n, mode, out_slope)。
文档随 TraderEdgAIFactor 源码维护,若 DLL 版本更新请以实际导出与行为为准。