MQL5標準ライブラリ・CTrade完全ガイド｜注文・決済・ポジション確認の実務基礎

MQL5でEAの注文処理を実装する時、標準ライブラリのCTradeを使うと、Buy、Sell、PositionClose、PositionModifyなどを比較的シンプルに書けます。MqlTradeRequestを直接組み立てる方法に比べて記述量を減らしやすく、基本的な成行注文、決済、SL/TP変更、注文結果確認を整理しやすいのが特徴です。

ただし、CTradeを使えば注文処理がすべて安全になるわけではありません。ロット、証拠金、スプレッド、StopLevel、FreezeLevel、取引許可、Magic Number、Hedging / Netting口座、retcode、約定後の取引イベント確認などは、EA側で明確に確認する必要があります。

特に実務では、CTradeのBuyやSellを呼ぶ前に、signal、filter、risk、executionの責務を分け、発注前チェックと注文結果ログを残すことが重要です。注文しない原因が、シグナル不成立なのか、スプレッドで止まったのか、証拠金不足なのか、CTradeのretcodeなのかを追える設計にしておく必要があります。

この記事では、MQL5標準ライブラリCTradeについて、Buy、Sell、PositionClose、PositionModify、ResultRetcode、SetExpertMagicNumber、SetDeviationInPoints、OrderCheckとの関係、Hedging / Netting口座での注意点、ログ設計、バックテスト確認を実務目線で整理します。

この記事は、MT5 / MQL5のEA開発、注文処理、決済処理、ポジション管理、ログ確認を目的とした技術記事です。特定の売買判断、利益、勝率、損失回避、推奨ロット、推奨銘柄を案内するものではありません。

この記事で確認すること

CTradeとは

CTradeは、MQL5標準ライブラリに含まれる取引用クラスです。成行注文、指値注文、逆指値注文、決済、注文変更、ポジション変更などを、関数呼び出しで扱いやすくするために用意されています。

MQL5では、MqlTradeRequestとMqlTradeResultを使って注文リクエストを直接組み立てる方法があります。一方、CTradeを使うと、Buy、Sell、PositionClose、PositionModifyのようなメソッドを使って、基本的な注文処理を簡潔に書けます。

ただし、CTradeは発注処理を簡略化するためのクラスであり、EAの設計そのものを代わりに行ってくれるものではありません。注文前の条件確認、ロット計算、証拠金確認、スプレッド確認、SL/TP距離確認、ログ設計はEA側で行います。

CTradeを使う前に設計を分ける

CTradeはexecution、つまり注文実行の責務に置くのが基本です。シグナル判定、フィルター、リスク確認、注文実行をすべてCTrade周辺に混ぜてしまうと、注文しない理由を追いにくくなります。

EA設計では、signal、filter、risk、executionを分けます。signalは買い候補・売り候補を返します。filterはスプレッドや時間帯などの取引環境を確認します。riskはロット、証拠金、StopLevel、SL/TP距離を確認します。executionは、CTradeで注文を送る責務です。

この分離により、CTrade.Buyが呼ばれなかった理由が明確になります。シグナルがなかったのか、フィルターで止まったのか、riskで止まったのか、CTradeのretcodeで失敗したのかを分けてログ確認できます。

#include <Trade/Trade.mqh>

CTrade trade;

void OnTick()
{
   if(!IsNewBar(_Symbol, PERIOD_CURRENT))
      return;

   int signal = EvaluateEntrySignal();

   if(signal == 0)
   {
      Print("ENTRY_SKIP reason=NO_SIGNAL");
      return;
   }

   if(!PassEntryFilters(signal))
      return;

   if(!CheckEntryRisk(signal))
      return;

   ExecuteEntryByCTrade(signal);
}

この例では、OnTickの中で直接CTrade.BuyやCTrade.Sellを書かず、最後にExecuteEntryByCTradeへ渡しています。CTradeは注文実行部分に限定し、判定やリスク確認とは分けます。

CTradeを使う基本準備

CTradeを使うには、標準ライブラリのTrade.mqhをincludeし、CTrade型のインスタンスを用意します。EA全体で使う場合は、グローバルにCTrade trade; のように宣言しておくことが多いです。

また、EAで注文する場合は、Magic Numberや許容スリッページを明確に設定しておくと管理しやすくなります。Magic Numberは、複数EAや裁量注文と区別するために重要です。

#include <Trade/Trade.mqh>

input long InpMagicNumber = 935001;
input int InpDeviationPoints = 20;

CTrade trade;

int OnInit()
{
   trade.SetExpertMagicNumber(InpMagicNumber);
   trade.SetDeviationInPoints(InpDeviationPoints);

   PrintFormat("INIT_CTRADE magic=%I64d deviation=%d",
               InpMagicNumber,
               InpDeviationPoints);

   return INIT_SUCCEEDED;
}

この例では、OnInitでMagic Numberと許容スリッページを設定しています。注文前に毎回設定しても動作しますが、EA全体の初期化時にログへ残しておくと確認しやすくなります。

Buyで買い注文を送る

CTradeのBuyは、買いの成行注文を送るために使います。基本的には、ロット、銘柄、価格、SL、TP、コメントを指定できます。価格を0にすると、通常は現在のAskを使う形で処理されます。

ただし、Buyを呼ぶ前に、取引許可、スプレッド、ロット、証拠金、StopLevel、最大ポジション数などを確認する必要があります。Buyの呼び出しだけを見て「発注処理は完成」と考えるのは危険です。

bool ExecuteBuy(double volume, double sl, double tp)
{
   ResetLastError();

   bool result = trade.Buy(volume,
                           _Symbol,
                           0.0,
                           sl,
                           tp,
                           "EA_BUY");

   PrintFormat("CTRADE_BUY result=%s retcode=%d deal=%I64u order=%I64u comment=%s last_error=%d",
               result ? "Y" : "N",
               trade.ResultRetcode(),
               trade.ResultDeal(),
               trade.ResultOrder(),
               trade.ResultComment(),
               GetLastError());

   return result;
}

この例では、Buyの戻り値だけでなく、ResultRetcode、ResultDeal、ResultOrder、ResultComment、GetLastErrorをログに出しています。注文処理の調査では、戻り値だけでなくretcodeとcommentを確認することが重要です。

Sellで売り注文を送る

CTradeのSellは、売りの成行注文を送るために使います。Buyと同様に、ロット、銘柄、価格、SL、TP、コメントを指定できます。売り注文では、現在のBid側を基準に考えるため、SL/TPの価格方向を間違えないようにします。

買いと売りでSL/TPの位置関係は逆になります。BUYではSLが現在価格より下、TPが上になることが多く、SELLではSLが現在価格より上、TPが下になることが多いです。この方向を誤ると、invalid stopsの原因になります。

bool ExecuteSell(double volume, double sl, double tp)
{
   ResetLastError();

   bool result = trade.Sell(volume,
                            _Symbol,
                            0.0,
                            sl,
                            tp,
                            "EA_SELL");

   PrintFormat("CTRADE_SELL result=%s retcode=%d deal=%I64u order=%I64u comment=%s last_error=%d",
               result ? "Y" : "N",
               trade.ResultRetcode(),
               trade.ResultDeal(),
               trade.ResultOrder(),
               trade.ResultComment(),
               GetLastError());

   return result;
}

BuyとSellは似ていますが、価格方向、SL/TP方向、スプレッド、注文条件を分けて確認します。ログ名もCTRADE_BUY、CTRADE_SELLのように分けておくと、あとから検索しやすくなります。

SL/TP価格を作る時の注意

CTradeでBuyやSellを使う時、SLとTPを指定する場合は、価格方向とStopLevelを確認します。銘柄によってpoint、digits、StopLevel、FreezeLevelが異なるため、固定値だけでSL/TPを作ると注文失敗の原因になります。

特に、XAUUSD、指数、仮想通貨CFDなどでは、通貨ペアと価格桁やpointの感覚が違う場合があります。SL/TPをpips感覚で固定すると、実際の価格距離がブローカー条件に合わないことがあります。

bool BuildStopsForMarketOrder(int signal, double stop_points, double take_points, double &sl, double &tp)
{
   double point = SymbolInfoDouble(_Symbol, SYMBOL_POINT);
   int digits = (int)SymbolInfoInteger(_Symbol, SYMBOL_DIGITS);

   double bid = SymbolInfoDouble(_Symbol, SYMBOL_BID);
   double ask = SymbolInfoDouble(_Symbol, SYMBOL_ASK);

   if(point <= 0.0 || bid <= 0.0 || ask <= 0.0)
   {
      Print("STOPS_FAIL reason=BAD_MARKET_PRICE");
      return false;
   }

   if(signal > 0)
   {
      sl = NormalizeDouble(ask - stop_points * point, digits);
      tp = NormalizeDouble(ask + take_points * point, digits);
   }
   else if(signal < 0)
   {
      sl = NormalizeDouble(bid + stop_points * point, digits);
      tp = NormalizeDouble(bid - take_points * point, digits);
   }
   else
   {
      Print("STOPS_FAIL reason=NO_SIGNAL");
      return false;
   }

   PrintFormat("STOPS_BUILT signal=%d sl=%.5f tp=%.5f", signal, sl, tp);
   return true;
}

この例では、BUYとSELLでSL/TPの方向を分けています。実務では、この後にStopLevelやFreezeLevelを確認し、必要ならOrderCheckで最終確認します。

PositionCloseでポジションを決済する

CTradeのPositionCloseは、保有ポジションを決済するために使います。銘柄指定で決済する方法や、チケットを指定して決済する方法があります。Hedging口座とNetting口座では、ポジションの扱いが異なるため、どのポジションを閉じるのかを明確にします。

単一ポジション前提のEAでは、_Symbolを指定してPositionCloseする設計でも扱いやすい場合があります。一方で、複数ポジション、複数EA、複数Magic Numberを扱う場合は、ポジション選択とMagic Number確認を慎重に行う必要があります。

bool CloseCurrentSymbolPosition()
{
   if(!PositionSelect(_Symbol))
   {
      PrintFormat("POSITION_CLOSE_SKIP reason=NO_POSITION symbol=%s", _Symbol);
      return false;
   }

   ResetLastError();

   bool result = trade.PositionClose(_Symbol);

   PrintFormat("CTRADE_POSITION_CLOSE result=%s retcode=%d deal=%I64u order=%I64u comment=%s last_error=%d",
               result ? "Y" : "N",
               trade.ResultRetcode(),
               trade.ResultDeal(),
               trade.ResultOrder(),
               trade.ResultComment(),
               GetLastError());

   return result;
}

この例では、対象銘柄のポジションがある場合だけPositionCloseを呼んでいます。決済できない場合も、ResultRetcodeとResultCommentを残すことで原因確認がしやすくなります。

PositionModifyでSL/TPを変更する

CTradeのPositionModifyは、保有ポジションのSL/TPを変更するために使います。トレーリングストップ、建値移動、利益確保、損切り位置変更などで使われます。

SL/TP変更では、FreezeLevelやStopLevelに注意が必要です。価格に近すぎる変更は拒否される場合があります。また、変更処理を毎ティックで実行するとログが増え、無駄な変更リクエストが増えるため、必要な時だけ実行する設計にします。

bool ModifyPositionStops(double new_sl, double new_tp)
{
   if(!PositionSelect(_Symbol))
   {
      PrintFormat("POSITION_MODIFY_SKIP reason=NO_POSITION symbol=%s", _Symbol);
      return false;
   }

   ResetLastError();

   bool result = trade.PositionModify(_Symbol, new_sl, new_tp);

   PrintFormat("CTRADE_POSITION_MODIFY result=%s retcode=%d sl=%.5f tp=%.5f comment=%s last_error=%d",
               result ? "Y" : "N",
               trade.ResultRetcode(),
               new_sl,
               new_tp,
               trade.ResultComment(),
               GetLastError());

   return result;
}

PositionModifyは便利ですが、価格距離や変更頻度を確認しないと失敗しやすい処理です。トレーリングや建値移動を入れる場合は、現在SLとの差、最小変更幅、変更済みフラグを管理すると安定しやすくなります。

SetExpertMagicNumberでEAを識別する

Magic Numberは、EAが出した注文やポジションを識別するための番号です。複数EAを同じ口座で動かす場合や、裁量注文とEA注文を分ける場合に重要です。

CTradeでは、SetExpertMagicNumberでMagic Numberを設定できます。これを設定しておくと、CTradeから送る注文にMagic Numberを付けられます。ただし、保有ポジションを確認する時は、PositionGetInteger(POSITION_MAGIC)などでMagic Numberを確認する必要があります。

input long InpMagicNumber = 935001;

int OnInit()
{
   trade.SetExpertMagicNumber(InpMagicNumber);

   PrintFormat("MAGIC_SET magic=%I64d", InpMagicNumber);

   return INIT_SUCCEEDED;
}

Magic Numberは、EAごと、戦略ごと、銘柄グループごとに分けることがあります。後からポジション管理やログ確認をしやすくするため、設計段階でルールを決めておくことが重要です。

SetDeviationInPointsと許容スリッページ

SetDeviationInPointsは、注文時に許容する価格ずれをpoints単位で設定するために使います。相場状況や銘柄によっては、注文リクエスト時の価格と約定価格がずれることがあります。

許容値を小さくしすぎると、注文が通りにくくなる場合があります。大きくしすぎると、想定より不利な価格で約定する可能性があります。銘柄、時間帯、スプレッド、EAの目的に応じて設定します。

input int InpDeviationPoints = 20;

int OnInit()
{
   trade.SetDeviationInPoints(InpDeviationPoints);

   PrintFormat("DEVIATION_SET points=%d", InpDeviationPoints);

   return INIT_SUCCEEDED;
}

許容スリッページは、注文成功率と約定価格のバランスに関係します。バックテストだけで判断せず、デモ口座や実チャートで注文結果ログを確認してください。

ResultRetcodeを必ず確認する

CTradeの注文メソッドはboolを返しますが、注文結果を確認する時はboolだけで判断しない方が安全です。ResultRetcode、ResultDeal、ResultOrder、ResultCommentを確認することで、注文がどう処理されたかを追いやすくなります。

注文が失敗した場合、retcodeやcommentに原因が出ることがあります。たとえば、取引不可、証拠金不足、無効な価格、無効なSL/TP、マーケットクローズ、リクオート、取引量不正などです。

void PrintCTradeResult(string action_name, bool result)
{
   PrintFormat("%s result=%s retcode=%d deal=%I64u order=%I64u comment=%s last_error=%d",
               action_name,
               result ? "Y" : "N",
               trade.ResultRetcode(),
               trade.ResultDeal(),
               trade.ResultOrder(),
               trade.ResultComment(),
               GetLastError());
}

注文処理ごとに同じ形式でログを出すと、Buy、Sell、PositionClose、PositionModifyの結果を比較しやすくなります。

OrderCheckとCTradeの役割分担

CTradeは注文を送るためのクラスですが、発注前の確認をすべて代替するものではありません。証拠金、ロット、StopLevel、SL/TP距離などを事前に確認したい場合は、OrderCheckやSymbolInfoを組み合わせます。

OrderCheckは、注文リクエストが通りそうかを事前に確認するために使います。CTradeで注文する前に、同等のMqlTradeRequestを作ってOrderCheckする設計もあります。特に、証拠金不足やinvalid stopsを減らしたい場合は、OrderCheckを使った発注前チェックが有効です。

実務では、risk責務でロットやSL/TP距離を確認し、必要に応じてOrderCheckを行い、通過したらexecution責務でCTradeを呼び出す構成にすると整理しやすくなります。

Hedging口座とNetting口座の違いに注意する

MQL5では、口座方式によってポジション管理の考え方が変わります。Hedging口座では同一銘柄に複数ポジションを持てる場合があります。Netting口座では同一銘柄のポジションが統合される形になります。

CTradeでPositionCloseやPositionModifyを使う時、Hedging口座とNetting口座で「どのポジションを対象にするか」の考え方が変わります。複数ポジションを持つEAでは、ticket、symbol、Magic Numberを確認して処理する必要があります。

単純にPositionClose(_Symbol)だけで決済する設計は、EAの仕様によっては十分ではありません。複数EAや複数Magic Numberを運用する場合は、対象ポジションを絞り込む関数を用意してください。

bool IsMyPositionSelected()
{
   if(!PositionSelect(_Symbol))
      return false;

   long magic = (long)PositionGetInteger(POSITION_MAGIC);

   if(magic != InpMagicNumber)
   {
      PrintFormat("POSITION_SKIP reason=MAGIC_MISMATCH position_magic=%I64d ea_magic=%I64d",
                  magic,
                  InpMagicNumber);
      return false;
   }

   return true;
}

この例では、選択したポジションのMagic Numberを確認しています。実際のHedging口座では、ポジション一覧をループしてticket単位で確認する設計が必要になる場合があります。

CTradeとOnTradeTransactionを組み合わせる

CTradeで注文を送った後、実際にどのような取引イベントが発生したかを追跡するには、OnTradeTransactionが役立ちます。CTradeの戻り値とResultRetcodeで注文送信結果を確認し、OnTradeTransactionで注文、約定、決済、変更イベントを追跡します。

注文処理のログと取引イベントのログを両方残すことで、OrderSendは成功したが約定がどう処理されたのか、決済イベントが発生したのか、通知対象にすべきイベントは何かを確認しやすくなります。

void OnTradeTransaction(const MqlTradeTransaction &trans,
                        const MqlTradeRequest &request,
                        const MqlTradeResult &result)
{
   PrintFormat("TRADE_TX type=%d order=%I64u deal=%I64u symbol=%s volume=%.2f price=%.5f retcode=%d",
               trans.type,
               trans.order,
               trans.deal,
               trans.symbol,
               trans.volume,
               trans.price,
               result.retcode);
}

OnTradeTransactionはイベントごとに呼ばれるため、ログの出しすぎには注意してください。通知へ接続する場合は、OnTradeTransactionで通知候補を作り、OnTimerで送信キューを処理する構成が扱いやすいです。

CTradeを使った注文処理のログ設計

CTradeを使うEAでは、注文前、注文時、注文後のログを分けると確認しやすくなります。注文しない理由と注文失敗の理由を混同しないことが重要です。

ログは、あとから検索しやすい固定名にします。CTradeの結果だけでなく、CTradeを呼ぶ前に止まった理由も残すことで、EAの挙動を正確に追いやすくなります。

バックテストで確認すること

CTradeを使ったEAをバックテストする時は、損益だけでなく、注文処理のログを確認します。BuyやSellが呼ばれた回数、ResultRetcode、注文失敗理由、決済理由、PositionModifyの失敗回数などを確認します。

バックテストでは、シグナルが出ているのに注文が少ない場合、filterで止まっているのか、riskで止まっているのか、CTradeの注文結果で失敗しているのかをログで分けて確認します。

また、バックテストと実チャートでは、スプレッド、約定、スリッページ、取引時間、ブローカー条件が異なる場合があります。CTradeのretcodeとcommentは、実チャート確認でも重要です。

よくある不具合と確認ポイント

CTradeを使ったEAでよくある不具合は、注文しない、決済しない、SL/TP変更が失敗する、別EAのポジションを閉じる、Magic Numberで識別できない、retcodeを確認していない、といったものです。

開発依頼前に整理する注文仕様

CTradeを使ったEAの開発や改修を依頼する場合は、売買条件だけでなく、注文仕様を整理してください。どの条件でBuyするのか、Sellするのか、どのロットで注文するのか、SL/TPをどう置くのか、決済条件は何か、Magic Numberはどう分けるのかを明確にします。

「CTradeで注文するEAを作りたい」だけでは、発注前チェック、口座方式、ロット計算、決済、ログ、通知、複数EA運用の仕様が不足します。注文処理はEAの中核なので、仕様段階で確認項目を分けることが重要です。

実務チェック表

よくある質問

CTradeを使えばOrderSendは不要ですか？

基本的な注文処理ではCTradeで十分な場合があります。ただし、MqlTradeRequestを細かく制御したい場合や、OrderCheck用のリクエストを明示的に作りたい場合は、MqlTradeRequestやOrderSendを直接扱う設計もあります。

CTradeの戻り値だけ見れば注文結果は分かりますか？

戻り値だけで判断しない方が安全です。ResultRetcode、ResultDeal、ResultOrder、ResultComment、GetLastErrorを確認してください。さらに、約定や決済イベントはOnTradeTransactionでも追跡すると確認しやすくなります。

Magic Numberは必ず必要ですか？

複数EA運用や裁量注文との区別を考えるなら、Magic Numberを設定する方が安全です。CTradeではSetExpertMagicNumberで設定できます。ポジション管理時にもPOSITION_MAGICを確認してください。

PositionClose(_Symbol)だけで決済してもよいですか？

EAの仕様によります。単一銘柄・単一ポジション前提なら扱いやすい場合がありますが、複数EA、複数Magic Number、Hedging口座では、ticketやMagic Numberで対象を絞る設計が必要になることがあります。

CTradeでもOrderCheckは使うべきですか？

証拠金、ロット、StopLevel、SL/TP距離を事前に確認したい場合は、OrderCheckを使うと検証しやすくなります。CTradeは注文実行、OrderCheckは発注前チェックとして役割を分けると整理しやすいです。

CTradeのログは何を残すべきですか？

Buy / Sell / PositionClose / PositionModifyの結果、ResultRetcode、ResultDeal、ResultOrder、ResultComment、GetLastErrorを残すと確認しやすくなります。注文前に止まった理由も、FILTER_BLOCKやRISK_BLOCKとして分けて残してください。

関連ページ

CTradeを使った注文処理を整理する時は、EA設計、イベント処理、OrderCheck、注文・ポジション管理、ロット・証拠金、Magic Number、CSVログ、バックテストもあわせて確認すると、実装と検証を進めやすくなります。

まとめ

MQL5標準ライブラリのCTradeを使うと、Buy、Sell、PositionClose、PositionModifyなどの注文処理を整理しやすくなります。ただし、CTradeは注文実行を簡略化するためのクラスであり、EAの発注前チェックやログ設計まで自動で解決するものではありません。

実務では、signal、filter、risk、executionを分け、CTradeはexecution責務に置くのが扱いやすいです。BuyやSellを呼ぶ前に、スプレッド、ロット、証拠金、StopLevel、SL/TP距離、Magic Number、最大ポジション数を確認してください。

注文結果は、CTradeの戻り値だけでなく、ResultRetcode、ResultDeal、ResultOrder、ResultComment、GetLastError、OnTradeTransactionのログで確認します。EAが注文しない理由、注文失敗の理由、決済できない理由を追えるようにしておくことが、開発・検証・運用で重要です。