01با این API چه میسازید؟
یک پنل کپیترید با برند خودتان؛ کاربر در سایت شما حساب گیرنده را متصل میکند و سرور شما حسابها، تنظیمات و گزارشها را از ایرانامکیوال مدیریت میکند.
مثال: یک مادر MT5 به سه گیرنده وصل است. اولی با لات ثابت ۰٫۱، دومی با حجم مادر و سومی با سقف ضرر روزانه ۵٪ کار میکند. تنظیمات و گزارش هر گیرنده با شناسه خودش مستقل است.
02پیشنیاز، کلید و امنیت
- پلن بیزینس فعال داشته باشید و ابتدا یک حساب مادر را در داشبورد ایرانامکیوال متصل کنید.
- در بخش «API وایتلیبل» کلید صادر کنید. مقدار آن فقط همان لحظه دیده میشود؛ در سرور خودتان ذخیره کنید.
- در همه درخواستها هدر Bearer را بفرستید. برای بدنه JSON، هدر Content-Type هم لازم است.
Base URL: https://iranmql.com/api/v1/copy
Authorization: Bearer YOUR_API_KEY
Content-Type: application/jsonحداکثر ۱۰ کلید فعال مجاز است. کلیدها از داشبورد قابل لغو هستند و با غیرفعال شدن پلن بیزینس، API هم غیرفعال میشود. مدیریت کلید با نشست داشبورد انجام میشود و بخشی از API مبتنی بر Bearer نیست.
03شروع سریع؛ از مادر تا کپی
مقادیر YOUR_API_KEY، MOTHER_ID و FOLLOWER_ID را جایگزین کنید. حسابها و پاسخهای زیر نمایشیاند.
۱. شناسه مادر را بخوانید
curl 'https://iranmql.com/api/v1/copy/accounts' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"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 را صریح بفرستید؛ در غیر این صورت مادر اول انتخاب میشود. رمز حسابها در پاسخ نیست.
۲. اتصال گیرنده را آزمایش کنید
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 -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 -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 به کاربر نشان دهید تا حدس نزند. پاسخ شامل نام بروکر و آدرسهای اتصال است.
curl 'https://iranmql.com/api/v1/copy/brokers?platform=MT5&q=FxPro' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"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 -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"}'{
"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 -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 | شناسه مادر انتخابی؛ برای دو مادر بهتر است همیشه صریح باشد. |
lotMode | fixed لات ثابت؛ 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 -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 'https://iranmql.com/api/v1/copy/followers/FOLLOWER_ID/daily-loss' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"enabled": true,
"limitPercent": 5,
"day": "2026-10-04",
"ready": true,
"breached": false,
"startEquity": 10000
}اگر ready: false باشد، وضعیت روز هنوز نمونهبرداری نشده و startEquity: null به معنی زیان صفر نیست. مبنای روز UTC است.
08توقف و ادامه کپی
برای یک گیرنده از مسیر وضعیت همان گیرنده استفاده کنید. برای توقف همه اتصالهای کپی، موتور را متوقف کنید.
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 -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 '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'{
"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 '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 | سرویس بروکر یا وضعیت گزارش/ریسک موقتاً در دسترس نیست. |
{ "error": "کلید API معتبر یا فعال نیست." }در پاسخهای دارای بدنه، کد HTTP و فیلدهای status یا ok را بررسی کنید. روی 429 با فاصله مناسب دوباره تلاش کنید. گزارش پرهزینه یک گیرنده را همزمان چند بار درخواست ندهید. رمز معاملاتی را فقط از سرور بفرستید و در لاگ ثبت نکنید.