راهنمای API — سیستم سیگنال متاتریدر ۵
بازگشت به پنل

راهنمای ارسال سیگنال

سازگار با قالب قبلی LBank — قالب وب‌هوک تریدینگ‌ویو بدون هیچ تغییری کار می‌کند؛ فقط URL عوض می‌شود.

۱. معرفی

این سیستم سیگنال‌های معاملاتی شما را از طریق یک REST API می‌گیرد، به‌صورت صف FIFO (به تفکیک نماد) نگه می‌دارد و اکسپرت متاتریدر ۵ نصب‌شده روی سرور، آن را معمولاً در کمتر از یک ثانیه روی حساب بروکر اجرا می‌کند — خرید/فروش با معکوس‌سازی خودکار جهت، SL و TP سمت بروکر از همان سفارش اول، و محاسبه خودکار حجم بر اساس پارامترهای ریسک. هر سیگنال دقیقاً یک‌بار اجرا می‌شود و مسیر کامل آن (از دریافت تا تیکت معامله) در پنل بلادرنگ با تمام جزئیات قابل ردگیری است.

۲. endpoint ها

متدمسیرنقشتوضیح
POST/api/v1/signalssenderثبت سیگنال — قالب تریدینگ‌ویو (Signal) یا قالب کامل (signalType)؛ کلید در هدر X-API-Key یا فیلد key بدنه
GET/api/v1/signals?state=&symbol=&fromUtc=&toUtc=&limit=sender / adminفهرست و فیلتر تاریخچه سیگنال‌ها
GET/api/v1/signals/{id}sender / adminجزئیات کامل یک سیگنال + تایم‌لاین رویدادها + گزارش EA (حجم، تیکت‌ها، قیمت پر شدن، slippage، retcode)
POST/api/v1/signals/{id}/cancelsender / adminانصراف — فقط قبل از تحویل به EA؛ بعد از تحویل خطای 409
POST/api/v1/ea/pollea (فقط 127.0.0.1)کانال دریافت سیگنال توسط اکسپرت + heartbeat (form-urlencoded، پاسخ pipe-delimited)
POST/api/v1/ea/signals/{id}/ackeaگزارش نتیجه اجرا (outcome/final/retcode/تیکت‌ها)
GET/api/v1/ea/statusadmin / panelوضعیت لحظه‌ای EA (بالانس، اکوییتی، AutoTrading، پوزیشن‌ها)
GET/healthعمومیسلامت سرویس برای watchdog بیرونی — {status, db, last_ea_poll_seconds, pending}؛ خرابی دیتابیس = 503
POST/api/v1/panel/ticketpanel / adminتیکت یک‌بارمصرف ۶۰ ثانیه‌ای اتصال SignalR پنل (هدر X-API-Key) — کلید بلندعمر هرگز در URL نمی‌نشیند
GET/panelpanel / adminپنل لاگ بلادرنگ (SignalR + polling جایگزین)
GET/scalaradmin / senderمستندات تعاملی OpenAPI

همه زمان‌ها UTC با قالب ISO-8601 هستند (مثل 2026-11-01T12:00:03.512Z). سقف بدنه 256KB است. ارسال‌ها محدود به حدود 10 درخواست در دقیقه به‌ازای هر کلید هستند (پاسخ 429).

۳. نمونه‌های دقیق

کلید را از کجا بگیرید؟ مقدار واقعی key / هدر X-API-Key را از ادمین سرور بگیرید — کلیدها هنگام نصب با اسکریپت deploy/deploy.ps1 تولید می‌شوند و مقدار پیش‌فرض CHANGE-ME در محیط Production باعث بالا نیامدن سرور می‌شود. در نمونه‌های زیر جای‌گذار <your-sender-key> را با همان کلید عوض کنید و هرگز آن را در جای عمومی نمی‌نویسید.

۳-۱. قالب تریدینگ‌ویو (Signal) — با Placeholders

در تنظیم Webhook تریدینگ‌ویو، آدرس https://<دامنه>/api/v1/signals را بگذارید و متن پیام را دقیقاً مثل زیر (جای‌گذارهای رسمی TV خودشان در لحظه ارسال جایگزین می‌شوند؛ {{close}} عدد خام تولید می‌کند — بدون کوتیشن):

{
  "Signal": "Buy",
  "Symbol": "{{ticker}}",
  "Price": {{close}},
  "TP_Price": 4100.0,
  "SL_Price": 3900.0,
  "Percent": 20.0,
  "Adverse": 100.0,
  "key": "<your-sender-key>",
  "Timeframe": "5m",
  "SignalType": "v3"
}

حداقلِ سیگنال معتبر BUY/SELL این است: Signal، Symbol، SL_Price و key — اگر Percent یا Adverse نیاید، پیش‌فرض پیکربندی‌شده سرور و فاصله تا SL مبنا می‌شود.

۳-۲. همان قالب با مقادیر ثابت (برای تست دستی)

{
  "Signal": "Buy",
  "Symbol": "XAUUSD",
  "Price": 4000.0,
  "TP_Price": 4100.0,
  "SL_Price": 3900.0,
  "Percent": 20.0,
  "Adverse": 100.0,
  "key": "<your-sender-key>"
}

۳-۳. قالب کامل (signalType) — برای ارسال اسکریپتی/دستی

{
  "signalType": "Buy",
  "symbol": "XAUUSD",
  "accounts": "mt5-live",
  "percent": 20.0,
  "fixedAmount": 0,
  "tp": 4100.0,
  "sl": 3900.0,
  "price": 4000.0,
  "adverseMoveUsd": 100.0,
  "timeframe": "5m",
  "version": "v3",
  "key": "<your-sender-key>"
}

fixedAmount اگر بزرگ‌تر از صفر باشد به‌جای درصد، همان مبلغ ثابت USDT ریسک می‌شود. accounts اختیاری است؛ نبودش = همه اکانت‌های فعال (مثل قبل).

۳-۴. curl

curl -X POST "https://<دامنه>/api/v1/signals" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-sender-key>" \
  -d '{"Signal":"Buy","Symbol":"XAUUSD","Price":4000.0,"TP_Price":4100.0,"SL_Price":3900.0,"Percent":20.0,"Adverse":100.0,"key":"<your-sender-key>"}'

۳-۵. PowerShell

$body = @'
{"Signal":"Buy","Symbol":"XAUUSD","Price":4000.0,"TP_Price":4100.0,"SL_Price":3900.0,"Percent":20.0,"Adverse":100.0,"key":"<your-sender-key>"}
'@
Invoke-RestMethod -Method Post -Uri 'https://<دامنه>/api/v1/signals' `
  -ContentType 'application/json; charset=utf-8' `
  -Headers @{ 'X-API-Key' = '<your-sender-key>' } `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

در PowerShell بدنه را با UTF8.GetBytes بفرستید تا متن فارسی/کاراکترهای خاص سالم بمانند.

۳-۶. پاسخ موفق

{
  "success": true,
  "message": "سیگنال دریافت و صف شد",
  "lbankOrderId": null,
  "details": {
    "signal_id": 1042,
    "state": "QUEUED",
    "accounts": ["mt5-live"],
    "duplicate": false
  }
}

ارسال تکراری همان سیگنال در پنجره ۵ ثانیه، همان پاسخ قبلی را با duplicate: true برمی‌گرداند — دابل‌کلیک یا تکرار alert ضرری ندارد.

۴. نگاشت فیلد قبلی → جدید

فیلد قبلی (LBank)فیلد اینجاتوضیح
Signalنوع سیگنالنگاشت واژگان در جدول پایین
Symbolsymbolنرمال‌شده به حروف بزرگ (XAUUSD)
Pricepriceقیمت چارت فرستنده — فقط مرجع ثبت انحراف (اختیاری)
TP_Pricetp⭐ قیمت TP — سمت بروکر در همان سفارش اول (تصمیم D7)
SL_Pricesl⭐ قیمت SL — سمت بروکر + مبنای فاصله ریسک
Percentpercent⚠️ معنایش عوض شده — بخش ۵ را بخوانید
AdverseadverseMoveUsdفاصله خلاف جهت؛ نبود → فاصله ورود تا SL
keykeyکلید احراز — تریدینگ‌ویو هدر نمی‌فرستد؛ اگر غایب باشد کلید پیش‌فرض سرور به‌کار می‌رود (مثل قبل)
Timeframetimeframeذخیره می‌شود، اثری بر اجرا ندارد
SignalTypeversionنگاشت version قبلی
accountsaccountscsv اکانت‌های هدف؛ نبود = همه
—fixedAmountجدید — ریسک ثابت USDT به‌جای درصد

نگاشت نوع سیگنال (هر بزرگ/کوچک‌حرفی پذیرفته می‌شود)

مقدار قبلینوع داخلیرفتار
Buy / MarketBuy / LongBUYمارکت + TP/SL سمت بروکر
Sell / MarketSell / ShortSELLقرینه
ForceClose / ManualClose / CloseFORCE_CLOSEبستن فوری فارغ از سود/زیان
Closebytp / CloseByTp / CloseTpCLOSE_TPبستن پشتیبان هنگام خوردن TP روی چارت فرستنده
TPUpdate / TP_UpdateTP_UPDATEفاز ۲ — تا فعال‌سازی با خطای 409 type_disabled رد می‌شود

فیلدهای قبلی که پذیرفته ولی نادیده گرفته می‌شوند

این فیلدها اگر بیایند خطا نمی‌دهند؛ در رویداد سیگنال با برچسب ignored_fields ثبت و در پنل هشدار داده می‌شوند:

orderType، limitPrice (MT5 فقط مارکت)، closePrice، openPrice (استراتژی limit — فاز آینده)، timeoutSeconds، delaySeconds (ماشین limit قبلی)، leverage (D9)، allowedSignal، Market، TP، Version

۵. دو تغییر معنایی مهم نسبت به سیستم قبلی

⚠️ ۱) Percent دیگر «درصد تخصیص موجودی به مارجین» نیست

Percent الان درصد ریسک از بالانس است (۰ تا ۱۰۰). مثلاً با بالانس 10,000 و Percent=20، یعنی اگر قیمت به SL برسد دقیقاً $2,000 ضرر می‌کنید — نه اینکه $2,000 مارجین بگیرد. مقدار قبلی‌تان را حتماً بازبینی کنید.

⚠️ ۲) فرمول حجم دیگر amount/price نیست — فاصله‌محور است

حجم = مبلغ ریسک ÷ زیانِ هر لات در فاصله خلاف جهت (که از SL_Price یا Adverse می‌آید). پس هرچه SL دورتر، لات کوچک‌تر — ریسک دلاری ثابت می‌ماند. TP و SL هم برخلاف قبل (که بعد از fill با retry ست می‌شد) در همان سفارش اول سمت بروکر قرار می‌گیرند و پوزیشن هیچ‌وقت بی‌حفاظ نمی‌ماند. مثال عددی کامل در بخش ۸.

۶. جدول خطاها

کدمعنیچه کار کنید
400نوع سیگنال/نماد نامعتبر، یا percent خارج از ۰ تا ۱۰۰، یا بدنه خرابمقادیر را با نمونه‌های بخش ۳ مقایسه کنید
401کلید غایب/نامعتبرفیلد key بدنه یا هدر X-API-Key را بررسی کنید
404اکانت ناموجود (فیلد accounts)نام اکانت را اصلاح کنید یا فیلد را حذف کنید
409تضاد: cancel بعد از تحویل، یا TP_UPDATE غیرفعال (type_disabled)سیگنال تحویل‌شده قابل انصراف نیست؛ TP_UPDATE فعلاً فاز ۲ است
413بدنه بزرگ‌تر از 256KBبدنه را کوچک کنید
404.13همان محدودیت سایز، ولی از سمت IIS — به‌جای 413 با این کد دیده می‌شودبدنه را کوچک کنید (maxAllowedContentLength)
429سقف نرخ ارسال (~۱۰ در دقیقه per-key)چند ثانیه صبر کنید؛ هدر Retry-After را ببینید
503کلید قطع‌کننده signals_enabled روی سرور خاموش شدهوضعیت اضطراری اپراتور است — با ادمین تماس بگیرید

مهم برای تریدینگ‌ویو: TV هیچ‌وقت ارسالش را تکرار نمی‌کند. اگر دقیقاً لحظه‌ی ارسال alert سرور پایین باشد، آن سیگنال همان‌جا می‌سوزد و فقط در لاگ alert خود تریدینگ‌ویو دیده می‌شود — نتیجه را در پنل چک کنید.

۷. معنی حالت‌های سیگنال (State ها)

حالتمعنانوع
RECEIVEDثبت شد؛ در صف تحویلغیرپایانی
DELIVEREDبه EA تحویل شد؛ در انتظار ack (بیش از ۳۰ ثانیه بدون ack = آلارم قرمز STUCK در پنل)غیرپایانی
EXECUTINGEA در حال اجرای آن استغیرپایانی
WAITING_MARKETبازار بسته است؛ با باز شدن سشن اجرا می‌شود (منقضی نمی‌شود)غیرپایانی
RECONCILINGرفع ابهام رتکد 10012 با جستجوی تاریخچه دیل‌هاغیرپایانی
EXECUTEDبا موفقیت اجرا شد (خروجی: OPENED / REVERSED / CLOSED / ALREADY_CLOSED)پایانی
FAILEDاجرا نشد — دلیل در پنل (مثل volume_below_min، insufficient_margin، oversize، autotrading_disabled)پایانی + آلارم قرمز
CLOSED_NOT_REOPENEDدر معکوس، بستن موفق بود ولی بازگشایی نه — حساب صاف است؛ هرگز بی‌صدا نمی‌ماندپایانی + آلارم قرمز
NO_POSITIONسیگنال بستن رسیده ولی پوزیشنی برای بستن نبود (مثلاً TP بروکر زودتر بسته) — خوش‌خیم؛ بازگشایی خودکار انجام نمی‌شودپایانی + هشدار زرد
SKIPPED_DUPLICATEتکراریِ قبلاً پردازش‌شده (watermark) — به‌جای اجرای دوبارهپایانی
SUPERSEDEDBUY/SELL جدیدتری برای همان نماد آمده و این سیگنالِ هنوز-تحویل‌نشده را جایگزین کرد — دقیقاً هم‌ارز MERGED/CANCELLED سیستم قبلی؛ همیشه آخرین بایاس اجرا می‌شودپایانی (اطلاعی)
SKIPPED_MARKET_MOVEDنگهبان دیرهنگام: قیمت موقع اجرا از TP (tp_passed) یا SL (sl_invalidated) گذشته بود — اجرا بی‌معنا بودپایانی
EXPIREDفقط اگر TTL در پیکربندی روشن باشد — پیش‌فرض خاموش استپایانی
CANCELEDفرستنده قبل از تحویل لغو کردپایانی
REJECTEDرد شده در ورودیپایانی
STUCKفقط نمایش پنل (در دیتابیس نیست) — DELIVERED بیش از ۳۰ ثانیه بدون ackنمایشی

چرا TTL حذف شد؟ (تصمیم D6)

در سیستم قبلی سیگنال‌ها مهلت انقضا داشتند. اینجا طبق تصمیم صریح شما («هیچ سیگنالی نباید miss بشه؛ بایاس‌ها همدیگه رو جابه‌جا می‌کنن») سیگنال‌ها هرگز منقضی نمی‌شوند: سازوکار TTL در کد هست ولی پیش‌فرض خاموش است. جایگزین آن دو چیز است: SUPERSEDED (بایاس جدیدتر، صفِ تحویل‌نشده قبلی همان نماد را کنار می‌زند) و نگهبان‌های دیرهنگام سمت EA (اگر قیمت تا لحظه اجرا از TP یا SL گذشته باشد، اجرا نمی‌شود و SKIPPED_MARKET_MOVED گزارش می‌شود). نتیجه: سیگنال آخر هفته، دوشنبه صبح با سشن باز اجرا می‌شود — مگر اینکه بازار دیگر منطقش را باطل کرده باشد.

۸. مثال محاسبه لات

فرمول (سمت EA، با مشخصات زنده نماد از بروکر):

risk        = Balance × Percent/100            (یا FixedAmount ثابت)
adverse     = Adverse  یا  |قیمت ورود − SL_Price|
loss_per_lot = (adverse ÷ tick_size) × tick_value_loss
lots        = risk ÷ loss_per_lot     → گرد به پایین به گامِ حجم نماد

مثال تأییدشده شما — بالانس 10,000$، Percent=20، ورود 4000 و SL_Price=3900 (فاصله 100$ یا Adverse=100):

risk         = 10,000 × 20%  = 2,000$
loss_per_lot = (100 ÷ 0.01) × 1$  = 10,000$   (قرارداد 100 اونسی، تیک 0.01، ارزش تیک 1$)
lots         = 2,000 ÷ 10,000 = 0.2 لات

۹. امنیت: کلید کجاست و چطور بچرخد

اگر فکر می‌کنید کلید لو رفته: اول بدنه وب‌هوک تریدینگ‌ویو را با کلید جدید به‌روز کنید و اجرای موفق را در پنل ببینید، بعد کلید قدیمی را غیرفعال کنید — چون TV ریتری نمی‌کند، ترتیب درستِ تعویض اهمیت دارد.