راهنمای ارسال سیگنال
سازگار با قالب قبلی LBank — قالب وبهوک تریدینگویو بدون هیچ تغییری کار میکند؛ فقط URL عوض میشود.
۱. معرفی
این سیستم سیگنالهای معاملاتی شما را از طریق یک REST API میگیرد، بهصورت صف FIFO (به تفکیک نماد) نگه میدارد و اکسپرت متاتریدر ۵ نصبشده روی سرور، آن را معمولاً در کمتر از یک ثانیه روی حساب بروکر اجرا میکند — خرید/فروش با معکوسسازی خودکار جهت، SL و TP سمت بروکر از همان سفارش اول، و محاسبه خودکار حجم بر اساس پارامترهای ریسک. هر سیگنال دقیقاً یکبار اجرا میشود و مسیر کامل آن (از دریافت تا تیکت معامله) در پنل بلادرنگ با تمام جزئیات قابل ردگیری است.
۲. endpoint ها
| متد | مسیر | نقش | توضیح |
|---|---|---|---|
| POST | /api/v1/signals | sender | ثبت سیگنال — قالب تریدینگویو (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}/cancel | sender / admin | انصراف — فقط قبل از تحویل به EA؛ بعد از تحویل خطای 409 |
| POST | /api/v1/ea/poll | ea (فقط 127.0.0.1) | کانال دریافت سیگنال توسط اکسپرت + heartbeat (form-urlencoded، پاسخ pipe-delimited) |
| POST | /api/v1/ea/signals/{id}/ack | ea | گزارش نتیجه اجرا (outcome/final/retcode/تیکتها) |
| GET | /api/v1/ea/status | admin / panel | وضعیت لحظهای EA (بالانس، اکوییتی، AutoTrading، پوزیشنها) |
| GET | /health | عمومی | سلامت سرویس برای watchdog بیرونی — {status, db, last_ea_poll_seconds, pending}؛ خرابی دیتابیس = 503 |
| POST | /api/v1/panel/ticket | panel / admin | تیکت یکبارمصرف ۶۰ ثانیهای اتصال SignalR پنل (هدر X-API-Key) — کلید بلندعمر هرگز در URL نمینشیند |
| GET | /panel | panel / admin | پنل لاگ بلادرنگ (SignalR + polling جایگزین) |
| GET | /scalar | admin / 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 | نوع سیگنال | نگاشت واژگان در جدول پایین |
Symbol | symbol | نرمالشده به حروف بزرگ (XAUUSD) |
Price | price | قیمت چارت فرستنده — فقط مرجع ثبت انحراف (اختیاری) |
TP_Price | tp | ⭐ قیمت TP — سمت بروکر در همان سفارش اول (تصمیم D7) |
SL_Price | sl | ⭐ قیمت SL — سمت بروکر + مبنای فاصله ریسک |
Percent | percent | ⚠️ معنایش عوض شده — بخش ۵ را بخوانید |
Adverse | adverseMoveUsd | فاصله خلاف جهت؛ نبود → فاصله ورود تا SL |
key | key | کلید احراز — تریدینگویو هدر نمیفرستد؛ اگر غایب باشد کلید پیشفرض سرور بهکار میرود (مثل قبل) |
Timeframe | timeframe | ذخیره میشود، اثری بر اجرا ندارد |
SignalType | version | نگاشت version قبلی |
accounts | accounts | csv اکانتهای هدف؛ نبود = همه |
| — | fixedAmount | جدید — ریسک ثابت USDT بهجای درصد |
نگاشت نوع سیگنال (هر بزرگ/کوچکحرفی پذیرفته میشود)
| مقدار قبلی | نوع داخلی | رفتار |
|---|---|---|
Buy / MarketBuy / Long | BUY | مارکت + TP/SL سمت بروکر |
Sell / MarketSell / Short | SELL | قرینه |
ForceClose / ManualClose / Close | FORCE_CLOSE | بستن فوری فارغ از سود/زیان |
Closebytp / CloseByTp / CloseTp | CLOSE_TP | بستن پشتیبان هنگام خوردن TP روی چارت فرستنده |
TPUpdate / TP_Update | TP_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 در پنل) | غیرپایانی |
| EXECUTING | EA در حال اجرای آن است | غیرپایانی |
| 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) — بهجای اجرای دوباره | پایانی |
| SUPERSEDED | BUY/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 لات
- مبنای درصد، Balance است (تصمیم D2؛ سوئیچ Equity در EA هست).
- هرگز به بالا گرد نمیشود — رد شدن از بودجه ریسک ممنوع است.
- اگر لات محاسبهشده زیر حداقل بروکر باشد، معامله انجام نمیشود و
FAILED(volume_below_min)گزارش میشود (سیاست skip-and-report). - قبل از ارسال، گیت مارجین یکبار حجم را در صورت نیاز کم میکند؛ ناتوانی =
FAILED(insufficient_margin). - کمیسیون و لوریج در فرمول لحاظ نمیشوند (تصمیم D9).
۹. امنیت: کلید کجاست و چطور بچرخد
- کلید در بدنه، نه در URL: تریدینگویو هدر سفارشی نمیفرستد؛ کلید را در فیلد
keyبدنه JSON بفرستید. هرگز کلید را در query string URL نگذارید — URL ها در لاگ IIS میمانند. اسکریپتهای خودتان بهتر است از هدرX-API-Keyاستفاده کنند. - ارتباط رمزنگاریشده: تریدینگویو فقط به HTTPS با گواهی معتبر وصل میشود؛ آدرس وبهوک حتماً
https://باشد. - کلیدها روی سرور فقط بهصورت هش sha256 ذخیره میشوند و در لاگها فقط «برچسب» کلید دیده میشود، نه خود کلید.
- چرخش کلید بدون داونتایم: کلید دوم را به پیکربندی سرور اضافه کنید (هر دو فعال میشوند) → چند روز ترافیک را در پنل روی کلید جدید تأیید کنید → کلید قدیم را حذف کنید. هیچ وقفهای در دریافت سیگنال پیش نمیآید.
- کلید فرستنده را جدا از کلید پنل/ادمین نگه دارید؛ هر نقش دسترسی خودش را دارد.
- کانال EA فقط از 127.0.0.1 قابل فراخوانی است و از اینترنت در دسترس نیست.
اگر فکر میکنید کلید لو رفته: اول بدنه وبهوک تریدینگویو را با کلید جدید بهروز کنید و اجرای موفق را در پنل ببینید، بعد کلید قدیمی را غیرفعال کنید — چون TV ریتری نمیکند، ترتیب درستِ تعویض اهمیت دارد.