IranMQL / APIبازگشت به سایت ←
مستندات توسعه‌دهندگان · پلن بیزینس

API کپی‌ترید وایت‌لیبل

حساب مادر و گیرنده‌های خود را به سایتتان وصل کنید، کپی معاملات را کنترل کنید و عملکرد هر حساب را با API ایران‌ام‌کیو‌ال گزارش بگیرید.

شروع سریعهمه مسیرها
اتصال و گزارش MT4 و MT5تا دو مادر در پلن بیزینس۱۲۰ درخواست در دقیقه

01با این API چه می‌سازید؟

یک پنل کپی‌ترید با برند خودتان؛ کاربر در سایت شما حساب گیرنده را متصل می‌کند و سرور شما حساب‌ها، تنظیمات و گزارش‌ها را از ایران‌ام‌کیو‌ال مدیریت می‌کند.

اتصال چند حسابدو مادر، گیرنده‌های متعدد و کنترل مستقل هر گیرنده.
انطباق نماد و حجمجست‌وجوی سرور بروکر، تشخیص نام نمادها و انتخاب روش محاسبه لات.
پایش و گزارشوضعیت موتور، سقف ضرر و تفکیک معاملات کپی، شخصی و نامشخص.

مثال: یک مادر MT5 به سه گیرنده وصل است. اولی با لات ثابت ۰٫۱، دومی با حجم مادر و سومی با سقف ضرر روزانه ۵٪ کار می‌کند. تنظیمات و گزارش هر گیرنده با شناسه خودش مستقل است.

02پیش‌نیاز، کلید و امنیت

  1. پلن بیزینس فعال داشته باشید و ابتدا یک حساب مادر را در داشبورد ایران‌ام‌کیو‌ال متصل کنید.
  2. در بخش «API وایت‌لیبل» کلید صادر کنید. مقدار آن فقط همان لحظه دیده می‌شود؛ در سرور خودتان ذخیره کنید.
  3. در همه درخواست‌ها هدر Bearer را بفرستید. برای بدنه JSON، هدر Content-Type هم لازم است.
آدرس پایه و هدرهاHTTP
Base URL: https://iranmql.com/api/v1/copy
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
مرز دسترسی: کلید فقط داده‌های صاحب خودش را می‌بیند، اما به همه گیرنده‌های همان صاحب دسترسی دارد. اگر در سایتتان چند مشتری دارید، سرور شما باید بررسی کند هر مشتری فقط گیرنده خودش را ببیند. کلید را در JavaScript مرورگر یا اپ موبایل قرار ندهید.

حداکثر ۱۰ کلید فعال مجاز است. کلیدها از داشبورد قابل لغو هستند و با غیرفعال شدن پلن بیزینس، API هم غیرفعال می‌شود. مدیریت کلید با نشست داشبورد انجام می‌شود و بخشی از API مبتنی بر Bearer نیست.

03شروع سریع؛ از مادر تا کپی

مقادیر YOUR_API_KEY، MOTHER_ID و FOLLOWER_ID را جایگزین کنید. حساب‌ها و پاسخ‌های زیر نمایشی‌اند.

۱. شناسه مادر را بخوانید

فهرست حساب‌هاcURL
curl 'https://iranmql.com/api/v1/copy/accounts' \
  -H 'Authorization: Bearer YOUR_API_KEY'
نمونه ساختار پاسخJSON نمایشی
{
  "status": "ok",
  "sender": { "id": "MOTHER_ID", "platform": "MT5", "account": "12345678" },
  "senders": [{ "id": "MOTHER_ID", "platform": "MT5", "account": "12345678" }],
  "followers": [],
  "copyAccess": { "tier": "business" }
}

شناسه را از senders[].id بردارید. اگر دو مادر دارید، هنگام ثبت گیرنده senderId را صریح بفرستید؛ در غیر این صورت مادر اول انتخاب می‌شود. رمز حساب‌ها در پاسخ نیست.

۲. اتصال گیرنده را آزمایش کنید

آزمایش MT5cURL
curl -X POST 'https://iranmql.com/api/v1/copy/test-connection' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"platform":"MT5","account":"87654321","server":"Broker-Demo","port":443,"password":"TRADING_PASSWORD"}'

برای MT4 و MT5 پاسخ ok: true یعنی اتصال زنده موفق بوده است. برای پلتفرم‌های دیگر، این مسیر فقط کامل بودن ورودی را بررسی می‌کند و اتصال واقعی به بروکر را تأیید نمی‌کند.

۳. گیرنده را ثبت کنید

لات ثابت و سقف ضرر ۵٪cURL
curl -X POST 'https://iranmql.com/api/v1/copy/followers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"حساب آزمایشی مشتری",
    "platform":"MT5",
    "account":"87654321",
    "server":"Broker-Demo",
    "port":443,
    "password":"TRADING_PASSWORD",
    "senderId":"MOTHER_ID",
    "copyEndsAt":null,
    "lotMode":"fixed",
    "fixedLot":0.10,
    "dailyLossLimitPercent":5,
    "positionSources":["manual"]
  }'

پاسخ موفق 201 شامل follower.id است. copyEndsAt: null یعنی بدون تاریخ پایان؛ در غیر این صورت زمان آینده را به قالب ISO 8601 بفرستید. این فیلد هنگام ساخت الزامی است.

۴. موتور را شروع و آماده شدنش را بررسی کنید

شروع و پایشcURL
curl -X POST 'https://iranmql.com/api/v1/copy/engine/start' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://iranmql.com/api/v1/copy/engine' \
  -H 'Authorization: Bearer YOUR_API_KEY'

شروع با 202 Accepted برمی‌گردد و اتصال ممکن است هنوز آماده نباشد. engine.ready را بررسی کنید؛ engine.error و engine.reconnecting نیز وضعیت اتصال را روشن می‌کنند.

04جست‌وجوی سرور بروکر

نام سرور را از فهرست MT4 یا MT5 به کاربر نشان دهید تا حدس نزند. پاسخ شامل نام بروکر و آدرس‌های اتصال است.

جست‌وجوی MT5cURL
curl 'https://iranmql.com/api/v1/copy/brokers?platform=MT5&q=FxPro' \
  -H 'Authorization: Bearer YOUR_API_KEY'
ساختار پاسخ؛ داده‌ها نمایشی‌اندJSON
{
  "status": "ok",
  "platform": "MT5",
  "results": [{
    "company": "Example Broker",
    "name": "Broker-Demo",
    "access": [{ "host": "broker.example.com", "port": 443 }]
  }],
  "cachedAt": "2026-10-01T10:00:00.000Z",
  "stale": false
}

stale: true یعنی فهرست از کش قدیمی آمده است. جست‌وجو حداکثر ۲۰ نتیجه می‌دهد. بعد از انتخاب سرور، مشخصات حساب را با POST /test-connection آزمایش کنید.

05تشخیص نام، پسوند و معادل نمادها

ممکن است مادر XAUUSD معامله کند، ولی گیرنده همان بازار را GOLD بنامد. این مسیر فهرست هر دو حساب را می‌خواند و نگاشت‌های پیشنهادی را برمی‌گرداند؛ معادل‌های شناخته‌شده طلا و داوجونز را هم بررسی می‌کند.

تشخیص برای گیرنده جدیدcURL
curl -X POST 'https://iranmql.com/api/v1/copy/detect-symbols' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"senderId":"MOTHER_ID","platform":"MT5","account":"87654321","server":"Broker-Demo","port":443,"password":"TRADING_PASSWORD"}'
نمونه پاسخJSON نمایشی
{
  "status": "ok",
  "mappings": [{ "sender": "XAUUSD", "receiver": "GOLD" }],
  "ambiguous": [{ "sender": "US30", "candidates": ["DJ30", "US30.cash"] }],
  "unmatched": [],
  "unchanged": 12,
  "preserved": 0,
  "checked": 14
}
نتیجه خودکار ذخیره نمی‌شود. نگاشت‌ها را بررسی کنید، موارد ambiguous را دستی انتخاب کنید و با symbolMappings هنگام ساخت یا ویرایش گیرنده ذخیره کنید. برای گیرنده ذخیره‌شده می‌توانید followerId بفرستید؛ رمز قبلی فقط با مشخصات اتصال یکسان استفاده می‌شود.
ذخیره نگاشت انتخابیcURL
curl -X PATCH 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"symbolMappings":[{"sender":"XAUUSD","receiver":"GOLD"},{"sender":"US30","receiver":"DJ30"}]}'

06تنظیمات هر گیرنده

تنظیمات را با POST /followers یا PATCH /followers/FOLLOWER_ID بفرستید. هر گیرنده می‌تواند مادر، حجم، نگاشت نماد و سقف ضرر جداگانه داشته باشد.

فیلدکاربرد
senderIdشناسه مادر انتخابی؛ برای دو مادر بهتر است همیشه صریح باشد.
lotModefixed لات ثابت؛ exact_lot حجم مادر؛ same_risk ریسک متناسب مادر؛ fixed_risk درصد ریسک گیرنده.
fixedLot / riskPercentمقدار لازم برای روش حجم انتخابی. روش‌های ریسکی به حد ضرر معتبر در معامله مادر نیاز دارند.
symbolPrefix / symbolSuffixپیشوند یا پسوند نماد گیرنده؛ مثلاً .pro.
symbolMappingsنگاشت صریح مانند [{"sender":"XAUUSD","receiver":"GOLD"}].
copySlTpکپی حد ضرر و حد سود؛ پیش‌فرض فعال است.
openDelay / closeDelayتأخیر تنظیم‌شده برای باز یا بسته شدن کپی.
positionSourcesشیوه ثبت سفارش در گیرنده: manual، expert، mobile یا web.
copyEndsAtزمان پایان آینده با ISO 8601؛ null یعنی بدون تاریخ پایان.
dailyLossLimitPercentسقف افت روزانه اکوییتی از ۰ تا ۱۰۰؛ صفر یعنی غیرفعال.
نکته: positionSources روش ثبت سفارش در گیرنده را تعیین می‌کند؛ فیلتر انتخاب معاملات مادر نیست.

پیش‌نمایش حجم

محاسبه آزمایشی لاتcURL
curl -X POST 'https://iranmql.com/api/v1/copy/preview-lot' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"lotMode":"fixed","fixedLot":0.10,"senderLot":0.20,"minLot":0.01,"maxLot":100,"lotStep":0.01}'

پاسخ شامل lot و formula است. این فقط پیش‌نمایش است؛ حجم نهایی به اطلاعات نماد، حد ضرر، محدودیت بروکر و اجرای سفارش هم وابسته است. برای روش‌های ریسکی، فاصله حد ضرر و ارزش تیک را نیز به محاسبه بدهید.

07سقف ضرر روزانه؛ دقیقاً چه می‌کند؟

اگر dailyLossLimitPercent: 5 باشد، موتور افت اکوییتی کل گیرنده را نسبت به نخستین اکوییتی ثبت‌شده در همان روز UTC می‌سنجد. با رسیدن به حد، باز شدن کپی‌های جدید تا روز بعد متوقف می‌شود. راه‌اندازی دوباره موتور این وضعیت را پاک نمی‌کند.

مهم: پوزیشن‌های باز خودکار بسته نمی‌شوند. به دلیل نوسان یا گپ قیمت، زیان نهایی می‌تواند از درصد تعیین‌شده بیشتر شود. برای بستن خودکار پوزیشن، مدیریت ریسک جداگانه لازم است.
وضعیت سقف ضررcURL
curl 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID/daily-loss' \
  -H 'Authorization: Bearer YOUR_API_KEY'
نمونه پاسخJSON نمایشی
{
  "enabled": true,
  "limitPercent": 5,
  "day": "2026-10-04",
  "ready": true,
  "breached": false,
  "startEquity": 10000
}

اگر ready: false باشد، وضعیت روز هنوز نمونه‌برداری نشده و startEquity: null به معنی زیان صفر نیست. مبنای روز UTC است.

08توقف و ادامه کپی

برای یک گیرنده از مسیر وضعیت همان گیرنده استفاده کنید. برای توقف همه اتصال‌های کپی، موتور را متوقف کنید.

توقف و ادامه یک گیرندهcURL
curl -X PATCH 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID/state' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"action":"stop"}'

curl -X PATCH 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID/state' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"action":"resume"}'

ادامه ممکن است با 409 رد شود؛ مثلاً اتصال نامعتبر است یا تاریخ پایان گذشته. توقف دستی جلوی کپی جدید را می‌گیرد و پوزیشن باز را نمی‌بندد.

توقف کل موتورcURL
curl -X POST 'https://iranmql.com/api/v1/copy/engine/stop' \
  -H 'Authorization: Bearer YOUR_API_KEY'
حذف یا قطع مادر با DELETE /sender?senderSlot=2 کل موتور این حساب بیزینس را متوقف می‌کند. برای توقف یک گیرنده، از PATCH /followers/{id}/state استفاده کنید.

09گزارش عملکرد و معاملات

گزارش از داده‌های بروکر برای گیرنده متصل MT4/MT5 ساخته می‌شود. بازه پیش‌فرض ۳۰ روز و حداکثر بازه یک درخواست ۳۶۶ روز است. مبلغ‌ها به ارز همان حساب هستند.

خلاصه عملکردcURL
curl 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID/performance?from=2026-10-01T00%3A00%3A00Z&to=2026-10-04T00%3A00%3A00Z' \
  -H 'Authorization: Bearer YOUR_API_KEY'
بخشی از ساختار پاسخJSON نمایشی
{
  "followerId": "FOLLOWER_ID",
  "currency": "USD",
  "totals": {
    "copied": { "closedRows": 8, "realizedNet": 54.20, "floatingNet": -2.10 },
    "personal": { "closedRows": 2, "realizedNet": 11.00, "floatingNet": 0 },
    "unattributed": { "closedRows": 1, "realizedNet": -3.50, "floatingNet": 0 }
  }
}

هر گروه openPositions، grossProfit، commission، swap و fee هم دارد. realizedNet نتیجه بسته‌شده پس از هزینه‌هاست و floatingNet نتیجه شناور را جدا نشان می‌دهد.

معاملات کپی‌شده، صفحه اولcURL
curl 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID/trades?origin=copied&limit=100&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

origin یکی از all، copied، personal و unattributed است. پاسخ total، offset، limit و trades دارد؛ هر صفحه حداکثر ۵۰۰ ردیف. برای صفحه بعد، offset را به اندازه limit افزایش دهید.

تفسیر گزارش: تشخیص کپی بر اساس تیکت گیرنده ثبت‌شده در موتور و نشان IMQL: در توضیح سفارش است. منشأ نامطمئن در unattributed می‌آید. در MT5 netting، معامله شخصی و کپی ممکن است در یک پوزیشن ادغام شوند؛ این تفکیک به‌تنهایی مبنای قطعی تسویه مالی نیست.

10مرجع همه مسیرها

مسیرها نسبت به https://iranmql.com/api/v1/copy هستند.

روش و مسیرکارکرد
GET /accountsمادرها، گیرنده‌ها و دسترسی پلن؛ بدون رمز.
GET /brokersجست‌وجو با platform=MT4|MT5 و q.
POST /test-connectionآزمایش مشخصات اتصال.
POST /senderثبت/ویرایش مادر با senderSlot: 1|2.
DELETE /senderقطع مادر انتخابی و توقف موتور.
POST /detect-symbolsپیشنهاد نگاشت نماد.
POST /followersثبت گیرنده.
GET /followers/{id}جزئیات عمومی گیرنده.
PATCH /followers/{id}ویرایش اتصال و تنظیمات کپی.
PATCH /followers/{id}/stateتوقف یا ادامه با stop|resume.
DELETE /followers/{id}حذف و قطع گیرنده.
POST /preview-lotپیش‌نمایش محاسبه لات.
GET /engineوضعیت موتور و اتصال‌ها.
POST /engine/startشروع موتور؛ پاسخ 202.
POST /engine/stopتوقف موتور.
GET /followers/{id}/daily-lossوضعیت سقف ضرر.
GET /followers/{id}/performanceخلاصه عملکرد تفکیک‌شده.
GET /followers/{id}/tradesفهرست معاملات با فیلتر و صفحه‌بندی.

برای مادر جدید، ابتدا POST /test-connection و سپس POST /sender را با شماره، سرور، رمز معاملاتی و senderSlot فراخوانی کنید. برای پسوند نماد مادر senderSymbolSuffix را تنظیم کنید.

11خطاها و الگوی پیاده‌سازی

کدمعنا
400ورودی نامعتبر؛ متن error را بخوانید.
401کلید نامعتبر یا لغوشده.
403پلن بیزینس غیرفعال یا محدودیت پلن.
404مسیر یا حساب در دسترس این کلید نیست.
409وضعیت ناسازگار؛ مثلاً اتصال یا تاریخ پایان.
422آزمایش اتصال یا دریافت نماد از بروکر ناموفق.
429محدودیت درخواست یا عملیات هم‌زمان؛ Retry-After را بررسی کنید.
502 / 503سرویس بروکر یا وضعیت گزارش/ریسک موقتاً در دسترس نیست.
نمونه خطاJSON
{ "error": "کلید API معتبر یا فعال نیست." }

در پاسخ‌های دارای بدنه، کد HTTP و فیلدهای status یا ok را بررسی کنید. روی 429 با فاصله مناسب دوباره تلاش کنید. گزارش پرهزینه یک گیرنده را هم‌زمان چند بار درخواست ندهید. رمز معاملاتی را فقط از سرور بفرستید و در لاگ ثبت نکنید.