gavindiaz/mt5cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a95ade1800b82ce6d8c09e76e1fc90fa5fc6808a
mt5cli/index.html
T
dceoy a95ade1800 deploy: f87683a431
2026-07-04 05:22:54 +00:00

687 lines
41 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Generic MT5 data and execution infrastructure for Python">
<meta name="author" content="dceoy">
<link rel="canonical" href="https://github.com/dceoy/mt5cli/">
<link rel="shortcut icon" href="img/favicon.ico">
<title>mt5cli API Documentation</title>
<link href="css/bootstrap.min.css" rel="stylesheet">
<link href="css/fontawesome.min.css" rel="stylesheet">
<link href="css/brands.min.css" rel="stylesheet">
<link href="css/solid.min.css" rel="stylesheet">
<link href="css/v4-font-face.min.css" rel="stylesheet">
<link href="css/base.css" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<link href="assets/_mkdocstrings.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body class="homepage">
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href=".">mt5cli API Documentation</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="nav-item">
<a href="." class="nav-link active" aria-current="page">Home</a>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">API Reference</a>
<ul class="dropdown-menu">
<li>
<a href="api/" class="dropdown-item">Overview</a>
</li>
<li>
<a href="api/public-contract/" class="dropdown-item">Public API Contract</a>
</li>
<li>
<a href="api/client/" class="dropdown-item">Client</a>
</li>
<li>
<a href="api/schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="api/converters/" class="dropdown-item">Converters</a>
</li>
<li>
<a href="api/exceptions/" class="dropdown-item">Exceptions</a>
</li>
<li>
<a href="api/cli/" class="dropdown-item">CLI</a>
</li>
<li>
<a href="api/sdk/" class="dropdown-item">SDK</a>
</li>
<li>
<a href="api/trading/" class="dropdown-item">Trading</a>
</li>
<li>
<a href="api/history/" class="dropdown-item">History Collection (SQLite)</a>
</li>
<li>
<a href="api/telemetry/" class="dropdown-item">Telemetry</a>
</li>
<li>
<a href="api/grafana/" class="dropdown-item">Grafana</a>
</li>
<li>
<a href="api/utils/" class="dropdown-item">Utils</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ms-md-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" class="nav-link disabled">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="api/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/dceoy/mt5cli/edit/master/docs/index.md" class="nav-link">Edit on dceoy/mt5cli
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-bs-toggle="collapse" data-bs-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-body-tertiary">
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="1"><a href="#mt5cli" class="nav-link">mt5cli</a>
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="2"><a href="#overview" class="nav-link">Overview</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#architecture" class="nav-link">Architecture</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#features" class="nav-link">Features</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#installation" class="nav-link">Installation</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#python-api-for-downstream-packages" class="nav-link">Python API for downstream packages</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#quick-start" class="nav-link">Quick Start</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#commands" class="nav-link">Commands</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#global-options" class="nav-link">Global Options</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#requirements" class="nav-link">Requirements</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#api-reference" class="nav-link">API Reference</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#development" class="nav-link">Development</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#license" class="nav-link">License</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="mt5cli">mt5cli<a class="headerlink" href="#mt5cli" title="Permanent link">&para;</a></h1>
<p>Generic MT5 data and execution infrastructure for Python applications.</p>
<h2 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">&para;</a></h2>
<p>mt5cli provides a stable <code>MT5Client</code> Python API, standardized dataset schemas, storage helpers, and a CLI for exporting MetaTrader 5 data. It is built on top of <a href="https://github.com/dceoy/pdmt5">pdmt5</a>, a pandas-based data handler for MetaTrader 5.</p>
<h2 id="architecture">Architecture<a class="headerlink" href="#architecture" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>pdmt5</strong> — canonical MT5 client, DataFrame/trading primitives, and MT5 constant parsing (<code>TIMEFRAME_*</code>, <code>COPY_TICKS_*</code>, order types).</li>
<li><strong>mt5cli</strong> — public <code>MT5Client</code> API, schema contracts, storage helpers, CLI commands, and SQLite history collection built on pdmt5.</li>
<li><strong>mt5api</strong> — sibling HTTP adapter for remote MT5 access; not a dependency of mt5cli.</li>
</ul>
<h2 id="features">Features<a class="headerlink" href="#features" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Multi-format export</strong>: CSV, JSON, Parquet, and SQLite3 output formats</li>
<li><strong>Auto-detection</strong>: Format detection from file extensions</li>
<li><strong>Comprehensive data access</strong>: Rates, ticks, account info, symbols, orders, positions, and trading history</li>
<li><strong>Flexible timeframes</strong>: Named timeframes (M1, H1, D1, etc.) and numeric values</li>
<li><strong>Connection management</strong>: Optional credentials, server, and timeout configuration</li>
<li><strong>SQLite rate loading</strong>: Load mt5cli-managed rate tables/views for offline workflows</li>
</ul>
<h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>pip<span class="w"> </span>install<span class="w"> </span>mt5cli
</code></pre></div>
<p>Parquet export is not included by default. To enable it, install the <code>parquet</code> extra:</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pip<span class="w"> </span>install<span class="w"> </span><span class="s2">&quot;mt5cli[parquet]&quot;</span>
</code></pre></div>
<h2 id="python-api-for-downstream-packages">Python API for downstream packages<a class="headerlink" href="#python-api-for-downstream-packages" title="Permanent link">&para;</a></h2>
<p>Import <code>MT5Client</code> for generic MT5 data access, schema normalization, and optional order primitives.</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">UTC</span><span class="p">,</span> <span class="n">datetime</span>
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="n">MT5Client</span><span class="p">,</span>
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="n">build_config</span><span class="p">,</span>
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a> <span class="n">collect_history</span><span class="p">,</span>
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a> <span class="n">mt5_session</span><span class="p">,</span>
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="p">)</span>
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.history</span><span class="w"> </span><span class="kn">import</span> <span class="n">load_rate_data</span><span class="p">,</span> <span class="n">resolve_rate_view_name</span>
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.schemas</span><span class="w"> </span><span class="kn">import</span> <span class="n">DataKind</span><span class="p">,</span> <span class="n">normalize_dataframe</span>
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.sdk</span><span class="w"> </span><span class="kn">import</span> <span class="n">minimum_margins</span><span class="p">,</span> <span class="n">recent_ticks</span>
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.utils</span><span class="w"> </span><span class="kn">import</span> <span class="n">Dataset</span><span class="p">,</span> <span class="n">export_dataframe</span>
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a>
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a><span class="c1"># Persistent session for multiple calls</span>
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a><span class="k">with</span> <span class="n">mt5_session</span><span class="p">(</span><span class="n">build_config</span><span class="p">(</span><span class="n">login</span><span class="o">=</span><span class="mi">12345</span><span class="p">,</span> <span class="n">server</span><span class="o">=</span><span class="s2">&quot;Broker-Demo&quot;</span><span class="p">))</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span>
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a> <span class="n">rates</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">copy_rates_range</span><span class="p">(</span>
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span>
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a> <span class="n">timeframe</span><span class="o">=</span><span class="s2">&quot;H1&quot;</span><span class="p">,</span>
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a> <span class="n">date_from</span><span class="o">=</span><span class="s2">&quot;2024-01-01&quot;</span><span class="p">,</span>
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a> <span class="n">date_to</span><span class="o">=</span><span class="s2">&quot;2024-02-01&quot;</span><span class="p">,</span>
<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a> <span class="p">)</span>
<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a> <span class="n">positions</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">positions</span><span class="p">()</span>
<a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a> <span class="n">check</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">order_check</span><span class="p">({</span><span class="s2">&quot;action&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;symbol&quot;</span><span class="p">:</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;volume&quot;</span><span class="p">:</span> <span class="mf">0.1</span><span class="p">})</span>
<a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a>
<a id="__codelineno-2-26" name="__codelineno-2-26" href="#__codelineno-2-26"></a><span class="c1"># Normalize MT5 frames to the public schema contract before storage</span>
<a id="__codelineno-2-27" name="__codelineno-2-27" href="#__codelineno-2-27"></a><span class="n">closed_rates</span> <span class="o">=</span> <span class="n">normalize_dataframe</span><span class="p">(</span>
<a id="__codelineno-2-28" name="__codelineno-2-28" href="#__codelineno-2-28"></a> <span class="n">rates</span><span class="p">,</span> <span class="n">DataKind</span><span class="o">.</span><span class="n">rates</span><span class="p">,</span> <span class="n">symbol</span><span class="o">=</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="n">timeframe</span><span class="o">=</span><span class="s2">&quot;H1&quot;</span>
<a id="__codelineno-2-29" name="__codelineno-2-29" href="#__codelineno-2-29"></a><span class="p">)</span>
<a id="__codelineno-2-30" name="__codelineno-2-30" href="#__codelineno-2-30"></a><span class="n">export_dataframe</span><span class="p">(</span><span class="n">closed_rates</span><span class="p">,</span> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;rates.csv&quot;</span><span class="p">),</span> <span class="s2">&quot;csv&quot;</span><span class="p">)</span>
<a id="__codelineno-2-31" name="__codelineno-2-31" href="#__codelineno-2-31"></a>
<a id="__codelineno-2-32" name="__codelineno-2-32" href="#__codelineno-2-32"></a><span class="c1"># Offline rate loading from mt5cli-managed SQLite history</span>
<a id="__codelineno-2-33" name="__codelineno-2-33" href="#__codelineno-2-33"></a><span class="n">view</span> <span class="o">=</span> <span class="n">resolve_rate_view_name</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="n">require_existing</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<a id="__codelineno-2-34" name="__codelineno-2-34" href="#__codelineno-2-34"></a><span class="n">offline_rates</span> <span class="o">=</span> <span class="n">load_rate_data</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-35" name="__codelineno-2-35" href="#__codelineno-2-35"></a>
<a id="__codelineno-2-36" name="__codelineno-2-36" href="#__codelineno-2-36"></a><span class="c1"># One-off helpers still work without instantiating a client</span>
<a id="__codelineno-2-37" name="__codelineno-2-37" href="#__codelineno-2-37"></a><span class="n">ticks</span> <span class="o">=</span> <span class="n">recent_ticks</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="n">seconds</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
<a id="__codelineno-2-38" name="__codelineno-2-38" href="#__codelineno-2-38"></a><span class="n">margins</span> <span class="o">=</span> <span class="n">minimum_margins</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">)</span>
<a id="__codelineno-2-39" name="__codelineno-2-39" href="#__codelineno-2-39"></a>
<a id="__codelineno-2-40" name="__codelineno-2-40" href="#__codelineno-2-40"></a><span class="n">collect_history</span><span class="p">(</span>
<a id="__codelineno-2-41" name="__codelineno-2-41" href="#__codelineno-2-41"></a> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span>
<a id="__codelineno-2-42" name="__codelineno-2-42" href="#__codelineno-2-42"></a> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">],</span>
<a id="__codelineno-2-43" name="__codelineno-2-43" href="#__codelineno-2-43"></a> <span class="n">date_from</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2024</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">UTC</span><span class="p">),</span>
<a id="__codelineno-2-44" name="__codelineno-2-44" href="#__codelineno-2-44"></a> <span class="n">date_to</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2024</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">UTC</span><span class="p">),</span>
<a id="__codelineno-2-45" name="__codelineno-2-45" href="#__codelineno-2-45"></a> <span class="n">datasets</span><span class="o">=</span><span class="p">{</span><span class="n">Dataset</span><span class="o">.</span><span class="n">rates</span><span class="p">,</span> <span class="n">Dataset</span><span class="o">.</span><span class="n">history_deals</span><span class="p">},</span>
<a id="__codelineno-2-46" name="__codelineno-2-46" href="#__codelineno-2-46"></a><span class="p">)</span>
</code></pre></div>
<p>Schema contracts live in <code>mt5cli.schemas</code> (<code>DataKind</code>, <code>validate_schema</code>, <code>normalize_dataframe</code>). Export and storage helpers are in <code>mt5cli.utils</code> (<code>Dataset</code>, <code>export_dataframe</code>) and <code>mt5cli.history</code>.</p>
<p><code>MT5Client.order_send()</code> is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly (the CLI requires <code>--yes</code> for <code>order-send</code>).</p>
<p><code>MT5Client.mt5_summary()</code> returns structured nested Python values. Use <code>MT5Client.mt5_summary_as_df()</code> when you need a one-row DataFrame for export.</p>
<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="c1"># Export account information to CSV</span>
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>mt5cli<span class="w"> </span>-o<span class="w"> </span>account.csv<span class="w"> </span>account-info
<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>
<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="c1"># Export EURUSD M1 rates to Parquet</span>
<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>mt5cli<span class="w"> </span>-o<span class="w"> </span>rates.parquet<span class="w"> </span>rates-from<span class="w"> </span>--symbol<span class="w"> </span>EURUSD<span class="w"> </span>--timeframe<span class="w"> </span>M1<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="w"> </span>--date-from<span class="w"> </span><span class="m">2024</span>-01-01<span class="w"> </span>--count<span class="w"> </span><span class="m">1000</span>
<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a>
<a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="c1"># Export ticks to JSON</span>
<a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a>mt5cli<span class="w"> </span>-o<span class="w"> </span>ticks.json<span class="w"> </span>ticks-from<span class="w"> </span>--symbol<span class="w"> </span>EURUSD<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a><span class="w"> </span>--date-from<span class="w"> </span><span class="m">2024</span>-01-01<span class="w"> </span>--count<span class="w"> </span><span class="m">500</span><span class="w"> </span>--flags<span class="w"> </span>ALL
<a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a>
<a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a><span class="c1"># Export symbols to SQLite3 with custom table name</span>
<a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a>mt5cli<span class="w"> </span>-o<span class="w"> </span>data.db<span class="w"> </span>--table<span class="w"> </span>symbols<span class="w"> </span>symbols<span class="w"> </span>--group<span class="w"> </span><span class="s2">&quot;*USD*&quot;</span>
<a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a>
<a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a><span class="c1"># Export with connection credentials from env or placeholders</span>
<a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a><span class="nv">MT5_LOGIN</span><span class="o">=</span><span class="m">12345</span><span class="w"> </span><span class="nv">MT5_PASSWORD</span><span class="o">=</span>secret<span class="w"> </span><span class="nv">MT5_SERVER</span><span class="o">=</span>MyBroker-Demo<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a><span class="w"> </span>mt5cli<span class="w"> </span>-o<span class="w"> </span>positions.csv<span class="w"> </span>positions
<a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a>mt5cli<span class="w"> </span>--login<span class="w"> </span><span class="s1">&#39;${MT5_LOGIN}&#39;</span><span class="w"> </span>--password<span class="w"> </span><span class="s1">&#39;${MT5_PASSWORD}&#39;</span><span class="w"> </span>--server<span class="w"> </span><span class="s1">&#39;${MT5_SERVER}&#39;</span><span class="w"> </span><span class="se">\</span>
<a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="w"> </span>-o<span class="w"> </span>positions.csv<span class="w"> </span>positions
</code></pre></div>
<h2 id="commands">Commands<a class="headerlink" href="#commands" title="Permanent link">&para;</a></h2>
<h3 id="rates">Rates<a class="headerlink" href="#rates" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>rates-from</code></td>
<td>Export rates from a start date</td>
</tr>
<tr>
<td><code>rates-from-pos</code></td>
<td>Export rates from a start position</td>
</tr>
<tr>
<td><code>latest-rates</code></td>
<td>Export latest rates</td>
</tr>
<tr>
<td><code>rates-range</code></td>
<td>Export rates for a date range</td>
</tr>
</tbody>
</table>
<h3 id="ticks">Ticks<a class="headerlink" href="#ticks" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ticks-from</code></td>
<td>Export ticks from a start date</td>
</tr>
<tr>
<td><code>ticks-range</code></td>
<td>Export ticks for a date range</td>
</tr>
<tr>
<td><code>ticks-recent</code></td>
<td>Export ticks from a trailing window</td>
</tr>
</tbody>
</table>
<h3 id="information">Information<a class="headerlink" href="#information" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>account-info</code></td>
<td>Export account information</td>
</tr>
<tr>
<td><code>terminal-info</code></td>
<td>Export terminal information</td>
</tr>
<tr>
<td><code>version</code></td>
<td>Export MetaTrader 5 version information</td>
</tr>
<tr>
<td><code>last-error</code></td>
<td>Export the last error information</td>
</tr>
<tr>
<td><code>symbols</code></td>
<td>Export symbol list</td>
</tr>
<tr>
<td><code>symbol-info</code></td>
<td>Export symbol details</td>
</tr>
<tr>
<td><code>symbol-info-tick</code></td>
<td>Export the last tick for a symbol</td>
</tr>
<tr>
<td><code>minimum-margins</code></td>
<td>Export minimum-volume margin summary</td>
</tr>
<tr>
<td><code>market-book</code></td>
<td>Export market depth (order book)</td>
</tr>
</tbody>
</table>
<h3 id="trading-state">Trading State<a class="headerlink" href="#trading-state" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>orders</code></td>
<td>Export active orders</td>
</tr>
<tr>
<td><code>positions</code></td>
<td>Export open positions</td>
</tr>
<tr>
<td><code>history-orders</code></td>
<td>Export historical orders</td>
</tr>
<tr>
<td><code>history-deals</code></td>
<td>Export historical deals</td>
</tr>
<tr>
<td><code>recent-history-deals</code></td>
<td>Export historical deals from a trailing window</td>
</tr>
<tr>
<td><code>mt5-summary</code></td>
<td>Export terminal/account status summary</td>
</tr>
<tr>
<td><code>order-check</code></td>
<td>Check funds sufficiency for a trade request (read-only, no <code>--yes</code>)</td>
</tr>
</tbody>
</table>
<h3 id="execution-live-mutating">Execution (live / mutating)<a class="headerlink" href="#execution-live-mutating" title="Permanent link">&para;</a></h3>
<p>These commands send requests to the live trade server and can place or close
real trades. Both require <code>--yes</code> for live execution.</p>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>order-send</code></td>
<td>Send a <strong>raw</strong> trade request directly to MT5 (<code>--yes</code> required; expert path — no extra validation)</td>
</tr>
<tr>
<td><code>close-positions</code></td>
<td>Close open positions by <code>--symbol</code> or <code>--ticket</code> (<code>--yes</code> required for live; <code>--dry-run</code> to preview; optional <code>--deviation</code> / <code>--comment</code> / <code>--magic</code>)</td>
</tr>
</tbody>
</table>
<p>Use <code>order-check</code> (Trading State) to validate funds before running <code>order-send --yes</code>.
<code>close-positions</code> is the safer high-level alternative that builds correct close
requests automatically. <code>order-send</code> is the expert raw path — downstream
applications should prefer dedicated closing helpers or their own risk controls.</p>
<h3 id="bulk-collection">Bulk Collection<a class="headerlink" href="#bulk-collection" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>collect-history</code></td>
<td>Collect rates, history-orders, and history-deals (ticks opt-in via <code>--dataset ticks</code>) for one or more symbols into a single SQLite database (optional cash-event/position views)</td>
</tr>
<tr>
<td><code>history-gaps</code></td>
<td>Export a SQLite-only one-row-per-gap report from managed rate compatibility views without connecting to MT5</td>
</tr>
</tbody>
</table>
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>mt5cli<span class="w"> </span>-o<span class="w"> </span>history.db<span class="w"> </span>collect-history<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span>--symbol<span class="w"> </span>EURUSD<span class="w"> </span>--symbol<span class="w"> </span>GBPUSD<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span>--date-from<span class="w"> </span><span class="m">2024</span>-01-01<span class="w"> </span>--date-to<span class="w"> </span><span class="m">2024</span>-02-01<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w"> </span>--dataset<span class="w"> </span>rates<span class="w"> </span>--dataset<span class="w"> </span>history-deals<span class="w"> </span><span class="se">\</span>
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w"> </span>--timeframe<span class="w"> </span>M1<span class="w"> </span>--flags<span class="w"> </span>ALL<span class="w"> </span>--if-exists<span class="w"> </span>append<span class="w"> </span>--with-views
</code></pre></div>
<p><code>collect-history</code> options:</p>
<table>
<thead>
<tr>
<th>Option</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--symbol/-s</code></td>
<td><em>required</em></td>
<td>Symbol to collect (repeat for multiple).</td>
</tr>
<tr>
<td><code>--date-from</code></td>
<td><em>required</em></td>
<td>Start date in ISO 8601.</td>
</tr>
<tr>
<td><code>--date-to</code></td>
<td><em>required</em></td>
<td>End date in ISO 8601.</td>
</tr>
<tr>
<td><code>--dataset</code></td>
<td>rates, history-orders, history-deals</td>
<td>Repeatable: <code>rates</code>, <code>ticks</code>, <code>history-orders</code>, <code>history-deals</code>. Ticks are opt-in: pass <code>--dataset ticks</code> to include them.</td>
</tr>
<tr>
<td><code>--timeframe</code></td>
<td><code>M1</code></td>
<td>Rates timeframe; recorded in a <code>timeframe</code> column on the <code>rates</code> table.</td>
</tr>
<tr>
<td><code>--flags</code></td>
<td><code>ALL</code></td>
<td>Tick copy flags forwarded to <code>copy_ticks_range</code>.</td>
</tr>
<tr>
<td><code>--if-exists</code></td>
<td><code>fail</code></td>
<td><code>append</code>, <code>replace</code>, or <code>fail</code> when a target table already exists.</td>
</tr>
<tr>
<td><code>--with-views</code></td>
<td>off</td>
<td>Add <code>cash_events</code> and <code>positions_reconstructed</code> views (requires the <code>history-deals</code> dataset).</td>
</tr>
</tbody>
</table>
<p>History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The <code>cash_events</code> view is derived from symbol-filtered <code>history_deals</code>, so account-level cash events with empty or non-matching symbols may be excluded. The <code>positions_reconstructed</code> view excludes positions with no closing deal, uses volume-weighted open/close prices, and reports reversal deals (<code>DEAL_ENTRY_INOUT</code>) via <code>volume_reversal</code> / <code>reversal_count</code>.</p>
<p>See the <a href="api/history/#entity-relationship-diagram">History schema diagram</a> for a sample ER layout of the resulting database.</p>
<h2 id="global-options">Global Options<a class="headerlink" href="#global-options" title="Permanent link">&para;</a></h2>
<table>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>-o, --output</code></td>
<td>Output file path (required)</td>
</tr>
<tr>
<td><code>-f, --format</code></td>
<td>Output format (auto-detected from extension if omitted)</td>
</tr>
<tr>
<td><code>--table</code></td>
<td>Table name for SQLite3 output (default: "data")</td>
</tr>
<tr>
<td><code>--login</code></td>
<td>Trading account login</td>
</tr>
<tr>
<td><code>--password</code></td>
<td>Trading account password (<code>MT5_PASSWORD</code>)</td>
</tr>
<tr>
<td><code>--server</code></td>
<td>Trading server name</td>
</tr>
<tr>
<td><code>--path</code></td>
<td>Path to MetaTrader5 terminal EXE file</td>
</tr>
<tr>
<td><code>--timeout</code></td>
<td>Connection timeout in milliseconds</td>
</tr>
<tr>
<td><code>--log-level</code></td>
<td>Logging level (DEBUG, INFO, WARNING, ERROR)</td>
</tr>
</tbody>
</table>
<h2 id="requirements">Requirements<a class="headerlink" href="#requirements" title="Permanent link">&para;</a></h2>
<ul>
<li>Python 3.11+</li>
<li>Windows OS (MetaTrader 5 requirement)</li>
<li>MetaTrader 5 platform</li>
</ul>
<h2 id="api-reference">API Reference<a class="headerlink" href="#api-reference" title="Permanent link">&para;</a></h2>
<p>Browse the API documentation for detailed module information:</p>
<ul>
<li><a href="api/cli/">CLI Module</a> - CLI application with data export and execution commands</li>
<li><a href="api/sdk/">SDK Module</a> - Programmatic read-only data collection API</li>
<li><a href="api/utils/">Utils Module</a> - Constants, parameter types, parsers, and export utilities</li>
</ul>
<h2 id="development">Development<a class="headerlink" href="#development" title="Permanent link">&para;</a></h2>
<p>This project follows strict code quality standards:</p>
<ul>
<li>Type hints required (strict mode)</li>
<li>Comprehensive linting with Ruff</li>
<li>Test coverage tracking</li>
<li>Google-style docstrings</li>
</ul>
<h2 id="license">License<a class="headerlink" href="#license" title="Permanent link">&para;</a></h2>
<p>MIT License - see <a href="https://github.com/dceoy/mt5cli/blob/main/LICENSE">LICENSE</a> file for details.</p></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="js/bootstrap.bundle.min.js"></script>
<script>
var base_url = ".",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="js/base.js"></script>
<script src="search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
<!--
MkDocs version : 1.6.1
Build Date UTC : 2026-07-04 05:22:51.759791+00:00
-->
Reference in New Issue View Git Blame Copy Permalink