From 6daf6060c3297de4d9cb40007f0eefbaddeb798b Mon Sep 17 00:00:00 2001
From: gavindiaz <cnws2018@gmail.com>
Date: Wed, 8 Jul 2026 06:42:59 +0000
Subject: [PATCH] Add basic usage example

---
 examples/01_basic_usage.py | 94 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 examples/01_basic_usage.py

diff --git a/examples/01_basic_usage.py b/examples/01_basic_usage.py
new file mode 100644
index 0000000..af42bcf
--- /dev/null
+++ b/examples/01_basic_usage.py
@@ -0,0 +1,94 @@
+"""
+01_basic_usage.py
+=================
+
+Basic usage of the mt5bridge-ccxt wrapper. Run this after starting
+your MT5Bridge HTTP service.
+
+Usage:
+    python 01_basic_usage.py
+"""
+
+import mt5bridge_ccxt
+
+# ─── 1. Create the exchange instance ──────────────────────────────────
+exchange = mt5bridge_ccxt.mt5bridge({
+    "apiKey": "your-mt5bridge-api-key",
+    "host": "http://localhost:8080",
+    # Map CCXT symbols to MT5 symbols (broker-specific suffix)
+    "symbols": {
+        "XAU/USD": "XAUUSDc",
+        "EUR/USD": "EURUSDc",
+        "GBP/USD": "GBPUSDc",
+    },
+})
+
+# ─── 2. Check status ─────────────────────────────────────────────────
+status = exchange.fetch_status()
+print("Bridge status:", status["status"])
+if status["status"] != "ok":
+    print("Bridge not ready, aborting.")
+    raise SystemExit(1)
+
+# ─── 3. Fetch markets ────────────────────────────────────────────────
+markets = exchange.fetch_markets()
+print(f"\nAvailable markets ({len(markets)}):")
+for m in markets:
+    print(f"  {m['symbol']:10s}  id={m['id']:12s}  digits={m['precision']['price']}  "
+          f"min_lot={m['limits']['amount']['min']}")
+
+# ─── 4. Fetch ticker ─────────────────────────────────────────────────
+ticker = exchange.fetch_ticker("XAU/USD")
+print(f"\nXAU/USD ticker:")
+print(f"  bid: {ticker['bid']}")
+print(f"  ask: {ticker['ask']}")
+print(f"  spread: {ticker['ask'] - ticker['bid']:.2f}")
+
+# ─── 5. Fetch OHLCV ──────────────────────────────────────────────────
+bars = exchange.fetch_ohlcv("XAU/USD", "1h", limit=5)
+print(f"\nXAU/USD H1 last 5 bars:")
+for ts, o, h, l, c, v in bars:
+    print(f"  ts={ts}  O={o}  H={h}  L={l}  C={c}  V={v}")
+
+# ─── 6. Fetch OHLCV by date range ────────────────────────────────────
+bars_july = exchange.fetch_ohlcv(
+    "XAU/USD", "1h",
+    params={"date_from": "2026-07-01", "date_to": "2026-07-03"},
+)
+print(f"\nXAU/USD H1 from 2026-07-01 to 2026-07-03: {len(bars_july)} bars")
+
+# ─── 7. Fetch balance ────────────────────────────────────────────────
+balance = exchange.fetch_balance()
+print(f"\nAccount balance:")
+for currency, total in balance["total"].items():
+    free = balance["free"][currency]
+    used = balance["used"][currency]
+    print(f"  {currency}: total={total}  free={free}  used={used}")
+
+# ─── 8. Fetch positions ──────────────────────────────────────────────
+positions = exchange.fetch_positions()
+print(f"\nOpen positions: {len(positions)}")
+for p in positions:
+    print(f"  #{p['id']:>10s}  {p['symbol']:10s}  {p['side']:5s}  "
+          f"vol={p['contracts']:.2f}  entry={p['entryPrice']}  "
+          f"pnl={p['unrealizedPnl']:.2f}  sl={p['stopLossPrice']}  tp={p['takeProfitPrice']}")
+
+# ─── 9. Place a market order ─────────────────────────────────────────
+# Uncomment to actually place an order:
+# order = exchange.create_order("XAU/USD", "market", "buy", 0.01, params={
+#     "sl": ticker["ask"] - 5.0,
+#     "tp": ticker["ask"] + 10.0,
+#     "magic": 123456,
+#     "comment": "basic_usage example",
+# })
+# print(f"\nOrder placed: #{order['id']}  status={order['status']}")
+
+# ─── 10. Read MQL5 indicator signal (if Alpha Trend is loaded) ───────
+try:
+    signal = exchange.mql5.alpha_trend_signal("XAUUSDc", "H1")
+    print(f"\nAlpha Trend (XAUUSD H1):")
+    print(f"  trend: {signal['trend']}  (1=long, -1=short)")
+    print(f"  buy signal: {signal['buy']}")
+    print(f"  sell signal: {signal['sell']}")
+except Exception as e:
+    print(f"\nMQL5 signal unavailable: {e}")