Metadata-Version: 2.5
Name: tickerall-nt-community
Version: 0.1.1
Summary: Independent community MetaTrader 5 adapter for NautilusTrader, via the hosted TickerAll API (no local MT5 terminal, any OS).
Project-URL: Homepage, https://github.com/miguelangelo78/tickerall-nt-community
Project-URL: Hosted API, https://tickerall.com
Author: Miguel Santos
License: MIT License
        
        Copyright (c) 2026 Miguel Santos
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: algotrading,forex,metatrader,mt5,nautilus,nautilustrader,tickerall,trading
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: nautilus-trader>=1.200.0
Requires-Dist: tickerall>=0.3.1
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# tickerall-nt-community

**An independent community MetaTrader 5 adapter for [NautilusTrader](https://nautilustrader.io)** —
stream live market data and backtest any MT5 broker (Exness, IC Markets, Pepperstone, FBS,
and more) **from Linux, macOS, or Windows, with no local MT5 terminal in the path.**
Live trading is coming in Phase 2 (see [Status](#status)).

> ⚠️ **Disclaimer:** This is an independent community project. It is **not** affiliated
> with, endorsed by, or supported by Nautech Systems Pty Ltd or the official NautilusTrader
> project.

> **Disclosure:** This adapter is built and maintained by Miguel Santos, who also builds and
> operates [TickerAll](https://tickerall.com) — the hosted MT5 API this adapter connects to.
> It is an open-source client for that API; you need a TickerAll account and API key to use it.

[![PyPI](https://img.shields.io/pypi/v/tickerall-nt-community.svg)](https://pypi.org/project/tickerall-nt-community/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Platform: any](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-brightgreen.svg)](#)

---

## What this is

`tickerall-nt-community` connects NautilusTrader to MetaTrader 5 brokers through
[TickerAll](https://tickerall.com), a **hosted MT5 API (REST + WebSocket)**. Because the broker
session lives on TickerAll's servers, the adapter itself is a **plain HTTP/WebSocket client** —
structurally a standard live adapter, like NautilusTrader's other venue integrations.

```
                              (any OS, no terminal)
NautilusTrader  ←→  tickerall-nt-community  ←→  TickerAll hosted API  ←→  MT5 broker
                     quote ticks + bars          (holds the broker
                     (live trading: Phase 2)      session)
```

### Why hosted?

The standard `MetaTrader5` Python library is **Windows-only** and needs a running MT5 terminal.
That forces algo devs onto a Windows box or a Wine/Docker workaround just to reach a broker.
This adapter removes both: the terminal runs on TickerAll's infrastructure, and your strategy
process talks to it over HTTPS/WSS from **any operating system** — a Linux server, a Mac laptop,
a container, a CI runner.

> If you already run a local Windows MT5 terminal and prefer to keep the broker session on your
> own machine, the [`mt5-connector`](https://github.com/aulekator/mt5-connector) community
> adapter is a good local-terminal alternative. This project is for people who want a hosted,
> OS-agnostic path instead.

---

## Status

This is an early release. Feature coverage is being built out in phases:

| Phase | Scope | Status |
| ----- | ----- | ------ |
| **1** | Market data — instruments, live quote ticks, historical bars | ✅ available |
| **2** | Execution — market/limit/stop orders, SL/TP, position + account reconciliation | ⏳ planned |

Live execution is intentionally **not** enabled yet — the execution client raises
`NotImplementedError` until Phase 2 is complete and tested. Use Phase 1 for data + backtesting.

---

## Requirements

- Python 3.11+
- A [TickerAll](https://tickerall.com) account and API key (`cf_...`)
- `nautilus_trader`
- `tickerall` (the official TickerAll Python SDK; installed as a dependency)

## Installation

```bash
pip install tickerall-nt-community
```

`nautilus_trader` and `tickerall` are installed automatically.

Or install from source:

```bash
git clone https://github.com/miguelangelo78/tickerall-nt-community.git
cd tickerall-nt-community
pip install -e .
```

See [`LOCAL_TESTING.md`](LOCAL_TESTING.md) for a full walkthrough on any OS.

## Quick start (data)

```python
from nautilus_trader.config import TradingNodeConfig, InstrumentProviderConfig
from nautilus_trader.live.node import TradingNode

from tickerall_nt import (
    TickerAllDataClientConfig,
    TickerAllLiveDataClientFactory,
)

config = TradingNodeConfig(
    trader_id="TESTER-001",
    data_clients={
        "TICKERALL": TickerAllDataClientConfig(
            api_key="cf_...",               # or TICKERALL_API_KEY
            account="12345678",             # your MT5 login   (or TICKERALL_ACCOUNT)
            server="Exness-MT5Trial7",      # your broker server (or TICKERALL_SERVER)
            password="...",                 # your broker password (or TICKERALL_PASSWORD)
            instrument_provider=InstrumentProviderConfig(load_all=True),
        ),
    },
)

node = TradingNode(config=config)
node.add_data_client_factory("TICKERALL", TickerAllLiveDataClientFactory)
node.build()
# ... add your strategy, then node.run()
```

See [`examples/data_tester.py`](examples/data_tester.py) for a runnable data-only
example, [`run.py`](run.py) for a quick smoke test with timings, and
[`LOCAL_TESTING.md`](LOCAL_TESTING.md) for step-by-step setup on any OS.

### Connecting your account

You configure the adapter with the same details you use to log into MetaTrader —
plus a TickerAll API key. **You never handle an internal TickerAll account id.**
The adapter opens (warms) the broker session for you.

| Field | Meaning | Env var |
| ----- | ------- | ------- |
| `api_key` | Your TickerAll API key | `TICKERALL_API_KEY` |
| `account` | Your MT5 login number | `TICKERALL_ACCOUNT` |
| `server` | Your broker server | `TICKERALL_SERVER` |
| `password` | Your broker password | `TICKERALL_PASSWORD` |

Prefer the environment variables for the password rather than hard-coding it.

> **Quick-test shortcut:** if you have already connected an account (it's *hot*)
> and it's the only hot account on your key, you can omit `account`/`server`/
> `password` and the adapter uses it — just the API key. Execution (Phase 2) will
> always require the explicit account fields.

---

## Symbol naming

MT5 symbols map to Nautilus instrument IDs as `{SYMBOL}.TICKERALL`, e.g. `EURUSD.TICKERALL`,
`XAUUSD.TICKERALL`, `BTCUSDm.TICKERALL`. Broker-specific suffixes (e.g. the Exness `m`) are
preserved verbatim as the raw symbol.

## Safety

TickerAll enforces demo/live status server-side; this adapter does not bypass it. Test strategies
on a **demo account** before trading anything funded. Trading is at your own risk.

## License

[MIT](LICENSE). NautilusTrader is licensed separately under LGPL-3.0.
