进阶版 API 文档说明

本页面向高端技术专家开放。若你需要在 EA 中深度对接 TraderEdgAIFactor.dll,需要每个 API 的完整入参、出参及参数说明,以及可直接复用的 MQ4/MQ5 代码片段,请以本页为准。

进阶版文档的价值与作用:

  • 减少对接歧义:每个 API 均给出入参、出参、参数含义与取值范围,避免因理解偏差导致调用错误。
  • 提供详细代码片段:MQ4 与 MQ5 双平台示例、注释与常见坑(如数组顺序、调用顺序、返回值检查),便于直接集成、减少反复试错与客服咨询。
  • 仅展示对接用 API:不涉及内部实现与框架,只列出你实际会调用的接口、参数与用法。

简单对接(极简代码与场景说明)请见 API 文档(简单版)

类型与常量

对接时用到的因子 ID、Action 常量及标准信号结构(MQ4 中结构体名可能为 TEAStandardSignalData,以头文件为准)。

因子 ID(统一接口使用)

常量说明
TEA_FACTOR_ENTROPY_HEDGE0EntropyHedge 熵场与对冲矩阵
TEA_FACTOR_TREND_PENALTY1TrendPenalty 趋势与惩罚
TEA_FACTOR_HEDGE_REGIME2HedgeRegime 趋势·震荡·刹车
TEA_FACTOR_TREND_STRENGTH_BRAKE3TrendStrengthBrake 多周期 R²·刹车强度

标准信号结构 TEAStandardSignal(MQ4 中为 TEAStandardSignalData)

struct TEAStandardSignal { double direction; // -1.0 / 0 / +1.0 double confidence; // 0.0 ~ 1.0 double strength; // 0.0 ~ 1.0 int regime; // 0=未知, 1=趋势, 2=震荡, -1=高风险 int action; // 0=FLAT, 1=LONG, 2=SHORT double score; // 综合评分 0~1 int valid; // 1=有效 0=无效 };

Action 枚举

常量
TEA_ACTION_FLAT0
TEA_ACTION_LONG1
TEA_ACTION_SHORT2

标准因子 API (TEA_*)

以下为对接时实际调用的 API:创建因子、传入 K 线、取回方向/动作/置信度等。handle 在 MQ4 中为 int;数组顺序 下标 0 = 最旧一根 K 线,size-1 = 最新必须先调用 Process 且返回 1,再调用 Get* 取信号,否则结果未定义。

TEA_FactorCreate
int TEA_FactorCreate(int factorId);
入参类型说明
factorIdint因子 ID:0=EntropyHedge,1=TrendPenalty,2=HedgeRegime,3=TrendStrengthBrake。见上方类型与常量。
返回值int成功返回非 0 句柄,失败返回 0。MQ4 用 int 接收;OnInit 中若为 0 应返回 INIT_FAILED。
TEA_FactorDestroy
void TEA_FactorDestroy(int handle);
入参类型说明
handleintTEA_FactorCreate 返回的句柄。OnDeinit 中必须调用,且仅对非 0 句柄调用,避免重复释放。
TEA_FactorProcess
int TEA_FactorProcess(int handle, double &opens[], double &highs[], double &lows[], double &closes[], double &volumes[], int size);
入参类型说明
handleint因子句柄,非 0。
opens, highs, lows, closes, volumesdouble[]开盘、最高、最低、收盘、成交量数组。顺序:下标 0 = 最旧 K 线,size-1 = 最新;与 MT 的 CopyOpen 等顺序一致(时间升序)。
sizeint数组长度,至少 50,建议 200。五组数组长度必须一致。
返回值int1=成功,0=失败。仅当返回 1 时方可调用 GetDirection/GetAction 等;否则不要读取信号。
TEA_FactorGetDirection / TEA_FactorGetAction / TEA_FactorGetRegime
double TEA_FactorGetDirection(int handle);
int TEA_FactorGetAction(int handle);
int TEA_FactorGetRegime(int handle);
入参说明
handle同上,且必须在本 tick 已成功调用过 TEA_FactorProcess(handle, ...) 且返回 1。
返回值说明
GetDirectiondouble:-1.0=偏空,0=中性,+1.0=偏多。用于过滤或仓位方向。
GetActionint:0=FLAT(观望),1=LONG(做多),2=SHORT(做空)。直接用于开平仓判断。
GetRegimeint:1=趋势,2=震荡,-1=高风险。可用于减仓或刹车逻辑。

其余 Get* API(信号与风控)

以下 API 与 GetDirection/GetAction/GetRegime 调用约定相同:必须先在本 tick 调用 TEA_FactorProcess 且返回 1,再调用下列 Get*;否则返回值未定义。入参均为 int handle(因子句柄),下表仅列出返回值类型与含义。

API签名返回值 / 说明
TEA_FactorGetConfidencedouble TEA_FactorGetConfidence(int handle);double,0~1。信号置信度,常用于过滤:仅当 confidence > 某阈值时开仓,或传入削单接口 TEA_ReductionRecommend 的 confidence 参数。
TEA_FactorGetStrengthdouble TEA_FactorGetStrength(int handle);double,0~1。信号强度,可用于仓位权重或过滤弱信号。
TEA_FactorGetScoredouble TEA_FactorGetScore(int handle);double,0~1。综合评分,与标准信号结构中的 score 一致,用于排序或过滤。
TEA_FactorIsValidint TEA_FactorIsValid(int handle);int:1=有效,0=无效。深度集成时建议必读:仅在返回 1 时依据 Action/Direction 开仓,否则本 tick 不交易,避免在无效信号上下单。
TEA_FactorGetAccuracyScoreint TEA_FactorGetAccuracyScore(int handle);int,0~100。准确度/质量分,与标准信号结构 accuracy_score 一致,可用于多因子加权或风控阈值。
TEA_FactorGetStopLossdouble TEA_FactorGetStopLoss(int handle);double。因子建议的止损价;0 表示本因子不提供止损,需自行计算或使用其他逻辑。
TEA_FactorGetTakeProfitdouble TEA_FactorGetTakeProfit(int handle);double。因子建议的止盈价;0 表示本因子不提供止盈。
TEA_FactorGetBrakeint TEA_FactorGetBrake(int handle);int:0 或 1。仅 HedgeRegime 因子:刹车标志,1=当前建议刹车(减仓/观望),可用于对冲 EA 的减仓或暂停加仓逻辑。
TEA_FactorGetATRdouble TEA_FactorGetATR(int handle);double。仅 HedgeRegime 因子:内部使用的 ATR 值,可用于与自算 ATR 对比或风控参考。
TEA_FactorGetBrakeStrengthdouble 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 做开平仓逻辑
}
#include <TraderEdgAIFactor.mqh>
int g_h = 0;   // factor handle, global

int OnInit() {
  g_h = TEA_FactorCreate(2);   // 2=HedgeRegime, or 0/1/3
  if (g_h == 0) { Print("TEA: factor create failed"); return INIT_FAILED; }
  return INIT_SUCCEEDED;
}

void OnDeinit(int reason) {
  if (g_h != 0) { TEA_FactorDestroy(g_h); g_h = 0; }  // only free non-zero
}

void OnTick() {
  if (g_h == 0) return;

  // OHLCV: index 0=oldest, n-1=newest, same order as 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;  // do not read signals on failure

  double dir = TEA_FactorGetDirection(g_h);
  int act = TEA_FactorGetAction(g_h);
  int regime = TEA_FactorGetRegime(g_h);
  // use dir / act / regime for open/close logic
}

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);
}
#include <TraderEdgAIFactor.mqh>
int g_h = 0;

int OnInit() {
  g_h = TEA_FactorCreate(TEA_FACTOR_HEDGE_REGIME);  // 2
  if (g_h == 0) { Print("TEA: factor create failed"); 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=oldest, n-1=newest

  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。

TEA_ReductionRecommend
int TEA_ReductionRecommend(double &profit_buy[], double &lots_buy[], int &open_time_buy[], int count_buy, double &profit_sell[], double &lots_sell[], int &open_time_sell[], int count_sell, int regime, double confidence, double target_net, int max_tail_count, double min_margin_base, int allow_cross_side, int risk_mode, int &out_action, int &out_side, int &out_loss_index, int &out_profit_start_index, int &out_profit_count, int &out_segment_side, int &out_cross_side, double &out_net_profit, double &out_reduction_potential, double &out_estimated_float_reduction, int &out_strategy_used);

入参说明

参数类型说明
profit_buy[], lots_buy[], open_time_buy[]数组多侧每笔持仓的浮动盈亏手数开仓时间(Unix 或 MQL 时间)。必须按开仓时间升序排列。
count_buyint多侧持仓笔数,与上面三个数组长度一致。
profit_sell[], lots_sell[], open_time_sell[]数组空侧同上,按开仓时间升序。
count_sellint空侧持仓笔数。
regimeint市场状态:1=趋势,2=震荡,-1=高风险。可与 TEA_FactorGetRegime 一致。
confidencedouble置信度 0~1。
target_netdouble目标净利,可传 0。
max_tail_countint尾端(亏损段)最多保留笔数。
min_margin_basedouble最小保证金基数,可传 0。
allow_cross_sideint是否允许跨侧削单:0=否,1=是。
risk_modeint风控模式,见头文件常量。

出参说明(DLL 写回,调用前需声明变量)

参数类型说明
out_actionint &1=单侧削多,2=单侧削空,3=跨侧削单。
out_sideint &亏损侧。
out_loss_indexint &亏损单索引。
out_profit_start_indexint &盈利段起始索引(先平这部分)。
out_profit_countint &盈利段笔数。执行顺序:先平盈利段 [start_index, start_index+count),再平亏损。
out_segment_side, out_cross_sideint &段侧、是否跨侧,见头文件。
out_net_profit, out_reduction_potential, out_estimated_float_reductiondouble &净利、削单潜能等,按需使用。
out_strategy_usedint &本次使用的策略标识。
返回值int1=本 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 判断是单侧还是跨侧
}
// 1. Prepare buy/sell arrays: fill profit_buy[], lots_buy[], open_time_buy[] and sell side, ascending by open time
// 2. Get regime, confidence (e.g. from TEA_FactorGetRegime/GetConfidence)
int regime = 1;
double confidence = 0.7;

// 3. Declare all output vars (MQ4 passes by reference)
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. Call (array lengths must match 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) {
  // Has recommendation: close profit segment first (from out_profit_start, out_profit_cnt bars), then loss
  // Use out_act/out_side to tell single-side vs cross-side
}

常见问题:① 多空数组必须按开仓时间升序,否则推荐结果可能错误。② 出参必须提前声明变量,MQ4 中通过引用传回。③ 先平盈利再平亏损。④ allow_cross_side=0 时不会返回跨侧建议。完整签名以 TraderEdgAIFactor.mqh 为准。

R² API · TEA_RSquared / TEA_RSquaredEx

无状态接口:传入收盘价数组与长度,返回 0~1 的趋势强度 R²。用于替代手写 R²,数值稳定、抗异常值。详见 算法因子库 RSquared。

TEA_RSquared
double TEA_RSquared(double &closes[], int count);
入参类型说明
closes[]double[]收盘价数组。下标 0 = 最旧 K 线,count-1 = 最新(时间升序)。
countint数组长度,即计算 R² 的 K 线根数。建议 2~512;count<2 时返回 0。
返回值double0~1,越接近 1 趋势越强,接近 0 表示无明显趋势。
TEA_RSquaredEx
double TEA_RSquaredEx(double &closes[], int count, int mode, double &out_slope);
入参类型说明
closes[], count同上同上。
modeint0=Pearson(数值稳定),1=Theil-Sen 稳健,2=指数加权。
out_slopedouble &可选,非 NULL 时写回拟合斜率。
返回值double0~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,可用于过滤或仓位权重
double closes[];
int n = 100;
ArrayResize(closes, n);
CopyClose(Symbol(), PERIOD_CURRENT, 0, n, closes);  // 0=oldest, n-1=newest
double r2 = TEA_RSquared(closes, n);
// r2 in 0~1; use for filter or position weight

MQ5 对接代码片段

double closes[];
int n = 100;
if (CopyClose(_Symbol, PERIOD_CURRENT, 0, n, closes) != n) return;
double r2 = TEA_RSquared(closes, n);
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 版本更新请以实际导出与行为为准。