مرجع API¶

المفاهيم الشائعة ¶

الحجم والأسعار وأنواع الأوامر ومدة الصلاحية

الحجم¶

يتم تحديد الحجم بـ السنتات (وحدات 0.0000001 لوت).

اللوتات	الحجم (سنتات)
0.01	`100,000`
0.1	`1,000,000`
1.0	`10,000,000`

الأسعار¶

قيم الأسعار بـ البيبيت. للتحويل: display_price = pipette_value / 10^pipDigits

بالنسبة لـ EURUSD (5 أرقام)، قيمة البيبيت 112345 = 1.12345.

أنواع الأوامر¶

النوع	الوصف	الحقول المطلوبة
`MARKET`	التنفيذ فورًا بالسعر الحالي	`symbolId`، `tradeSide`، `volume`
`LIMIT`	التنفيذ بسعر الحد أو أفضل	+ `limitPrice`
`STOP`	التفعيل عندما يصل السوق إلى سعر الإيقاف	+ `stopPrice`
`MARKET_RANGE`	التنفيذ ضمن نطاق سعري	+ `baseSlippagePrice`
`STOP_LIMIT`	أمر محدد يتم تفعيله عند سعر الإيقاف	+ `stopPrice`، `limitPrice`

مدة الصلاحية¶

السياسة	الوصف
`GOOD_TILL_CANCEL`	يظل الأمر نشطًا حتى يتم تنفيذه أو إلغاؤه
`GOOD_TILL_DATE`	ينتهي الأمر في `expirationTimestamp` المحدد
`IMMEDIATE_OR_CANCEL`	تنفيذ ما هو متاح فورًا، وإلغاء الباقي

معلومات الحساب ¶

GET /v1/balance Get account balance

يُرجع رصيد الحساب ورأس المال والهامش الحر.

المعلمات

لا توجد معاملات.

الاستجابات

200 استجابة ناجحة

Response body

{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}

الحقل	النوع	الوصف
`balance`	double	رصيد الحساب بعملة الإيداع
`equity`	double	الرصيد + الربح والخسارة العائم
`freeMargin`	double	الهامش المتاح للصفقات الجديدة
`balanceVersion`	int64	عداد إصدار الرصيد
`moneyDigits`	int32	الأماكن العشرية للقيم النقدية
`depositAssetId`	int64	معرّف أصل عملة الإيداع

GET /v1/symbols الحصول على الرموز المتاحة

يُرجع جميع الرموز المتاحة للتداول على الحساب.

المعلمات

لا توجد معاملات.

الاستجابات

200 مصفوفة من كائنات Symbol

Response body

[
  {
    "symbolId": 1,
    "symbolName": "EURUSD",
    "enabled": true,
    "baseAssetId": 2,
    "quoteAssetId": 1,
    "description": "Euro vs US Dollar"
  }
]

Symbol

الحقل	النوع	الوصف
`symbolId`	int64	معرّف الرمز (يُستخدم في استدعاءات API الأخرى)
`symbolName`	string	اسم الرمز (مثل "EURUSD")
`enabled`	boolean	ما إذا كان الرمز قابلاً للتداول
`baseAssetId`	int64	معرّف الأصل الأساسي
`quoteAssetId`	int64	معرّف أصل التسعير
`description`	string	وصف يمكن قراءته

GET /v1/assets الحصول على الأصول المتاحة

يُرجع الأصول المتاحة (العملات).

المعلمات

لا توجد معاملات.

الاستجابات

200 مصفوفة من كائنات Asset

Response body

[
  {
    "assetId": 1,
    "name": "USD",
    "displayName": "US Dollar"
  }
]

Asset

الحقل	النوع	الوصف
`assetId`	int64	معرّف الأصل
`name`	string	رمز الأصل (مثل "USD")
`displayName`	string	اسم العرض

بيانات السوق ¶

GET /v1/prices الحصول على الأسعار الفورية

يُرجع أسعار العرض/الطلب الحالية للرموز المحددة. هذه لقطة - لا تدعم واجهة API البث المباشر.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`symbolId`	query	int64[]		معرّفات الرموز مفصولة بفواصل

الاستجابات

200 مصفوفة من كائنات SpotPrice

Response body

[
  {
    "symbolId": 1,
    "bid": 112340,
    "ask": 112355,
    "high": 112890,
    "low": 111950,
    "sessionClose": 112100,
    "timestamp": 1700000000000
  }
]

SpotPrice

الحقل	النوع	الوصف
`symbolId`	int64	معرف الرمز
`bid`	int64	أفضل سعر عرض (بيبيت)
`ask`	int64	أفضل سعر طلب (بيبيت)
`high`	int64	أعلى سعر في الجلسة (بيبيت)
`low`	int64	أدنى سعر في الجلسة (بيبيت)
`sessionClose`	int64	إغلاق الجلسة السابقة (بيبيت)
`timestamp`	int64	الطابع الزمني للتسعير (epoch ms)

GET /v1/trendbars الحصول على بيانات OHLCV التاريخية

يُرجع بيانات الشموع اليابانية التاريخية (OHLCV) لرمز.

المعلمات

الاسم	موجود في	النوع	افتراضي	الوصف
`symbolId`	query	int64	–	معرف الرمز
`period`	query	string	–	فترة الشمعة
`fromTimestamp`	query	string	–	وقت البدء (ISO-8601)
`toTimestamp`	query	string	–	وقت الانتهاء (ISO-8601)
`count`	query	int32	`100`	الحد الأقصى للأشرطة المراد إرجاعها

الفترات المتاحة

M_1 M_2 M_3 M_4 M_5 M_10 M_15 M_30 H_1 H_2 H_3 H_4 H_6 H_8 H_12 D_1 W_1 MN_1

الاستجابات

200 مصفوفة من كائنات Trendbar

Response body

[
  {
    "timestamp": 1700000000000,
    "open": 112340.0,
    "high": 112890.0,
    "low": 111950.0,
    "close": 112500.0,
    "volume": 4521
  }
]

Trendbar

الحقل	النوع	الوصف
`timestamp`	int64	وقت فتح الشريط (epoch ms)
`open`	double	سعر الافتتاح (بيبيت)
`high`	double	أعلى سعر (بيبيت)
`low`	double	أدنى سعر (بيبيت)
`close`	double	سعر الإغلاق (بيبيت)
`volume`	int64	حجم التيك

الأوامر ¶

POST /v1/orders تقديم أمر جديد

يقدم أمر تداول جديد. يُرجع ExecutionResponse.

المعلمات

لا توجد معاملات مسار أو استعلام.

نص الطلب application/json

الحقل	النوع	الوصف
`symbolId`	int64	الرمز المراد تداوله
`orderType`	string	`MARKET`, `LIMIT`, `STOP`, `MARKET_RANGE`, `STOP_LIMIT`
`tradeSide`	string	`BUY` أو `SELL`
`volume`	int64	الحجم بالسنت
`limitPrice`	double	سعر الحد - مطلوب لـ `LIMIT`، `STOP_LIMIT`
`stopPrice`	double	سعر تفعيل الإيقاف - مطلوب لـ `STOP`، `STOP_LIMIT`
`stopLoss`	double	سعر إيقاف الخسارة
`takeProfit`	double	سعر جني الأرباح
`comment`	string	تعليق نصي حر (بحد أقصى 256 حرفًا)
`label`	string	تسمية البوت (بحد أقصى 100 حرف)
`timeInForce`	string	`GOOD_TILL_CANCEL`, `GOOD_TILL_DATE`, `IMMEDIATE_OR_CANCEL`
`baseSlippagePrice`	double	السعر الأساسي للانزلاق – مطلوب لـ `MARKET_RANGE`
`slippageInPoints`	int32	الحد الأقصى للانزلاق بالنقاط
`expirationTimestamp`	int64	الطابع الزمني لانتهاء الصلاحية (إيبوك بالميلي ثانية) – لـ `GOOD_TILL_DATE`

Example request body

{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}

الاستجابات

200 ExecutionResponse – تم قبول الأمر أو تنفيذه

400 INVALID_REQUEST أو TRADING_BAD_VOLUME

422 NOT_ENOUGH_MONEY

409 MARKET_CLOSED

Example success response

{
  "orderId": 12345,
  "positionId": 67890,
  "executionType": "ORDER_FILLED",
  "order": { "..." : "..." },
  "position": { "..." : "..." },
  "deal": { "..." : "..." }
}

GET /v1/orders الحصول على الأوامر المعلقة

يُرجع جميع الأوامر المعلقة (غير المنفذة).

المعلمات

لا توجد معاملات.

الاستجابات

200 مصفوفة من كائنات الأوامر المعلقة

PUT /v1/orders/{orderId} تعديل أمر معلق

يعدّل أمرًا معلقًا موجودًا. يُرجع ExecutionResponse.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`orderId`	path	int64		الأمر المراد تعديله

نص الطلب application/json

أي مجموعة فرعية من الحقول التالية.

الحقل	النوع	الوصف
`volume`	int64	الحجم الجديد بالسنت
`limitPrice`	double	سعر الحد الجديد
`stopPrice`	double	سعر الإيقاف الجديد
`stopLoss`	double	سعر إيقاف الخسارة الجديد
`takeProfit`	double	سعر جني الأرباح الجديد
`expirationTimestamp`	int64	الطابع الزمني الجديد لانتهاء الصلاحية (إيبوك بالميلي ثانية)

الاستجابات

200 ExecutionResponse مع ORDER_REPLACED

404 الأمر غير موجود

DELETE /v1/orders/{orderId} إلغاء أمر معلق

يلغي أمرًا معلقًا. يُرجع ExecutionResponse.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`orderId`	path	int64		الأمر المراد إلغاؤه

الاستجابات

200 ExecutionResponse مع ORDER_CANCELLED

404 الأمر غير موجود

GET /v1/orders/history الحصول على سجل الأوامر

يُرجع الأوامر التاريخية ضمن نطاق زمني.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`fromTimestamp`	query	string		وقت البدء (ISO-8601)
`toTimestamp`	query	string		وقت الانتهاء (ISO-8601)

الاستجابات

200 OrderListResponse

الحقل	النوع	الوصف
`orders`	Order[]	مصفوفة من الأوامر التاريخية
`hasMore`	boolean	ما إذا كانت صفحات إضافية متاحة

مراكز ¶

GET /v1/positions الحصول على المراكز المفتوحة

يُرجع جميع المراكز المفتوحة والأوامر المعلقة.

المعلمات

لا توجد معاملات.

الاستجابات

200 مصفوفة من كائنات المراكز

Response body

[
  {
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "entryPrice": 112345.0,
    "stopLoss": 112000.0,
    "takeProfit": 113000.0,
    "unrealizedPnl": 155.25,
    "commission": -7.00,
    "swap": -1.20
  }
]

مركز

الحقل	النوع	الوصف
`positionId`	int64	معرّف المركز
`symbolId`	int64	معرف الرمز
`tradeSide`	string	`BUY` أو `SELL`
`volume`	int64	الحجم بالسنت
`entryPrice`	double	سعر الدخول VWAP
`stopLoss`	double	سعر إيقاف الخسارة
`takeProfit`	double	سعر جني الأرباح
`unrealizedPnl`	double	الربح/الخسارة العائمة
`commission`	double	العمولة المحملة
`swap`	double	مبلغ السواب

GET /v1/positions/{positionId} الحصول على تفاصيل المركز

يُرجع مركزًا مع أوامره وصفقاته ذات الصلة.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`positionId`	path	int64		معرّف المركز

الاستجابات

200 PositionDetailResponse

الحقل	النوع	الوصف
`position`	Position	كائن المركز
`orders`	Order[]	الأوامر ذات الصلة
`deals`	Deal[]	الصفقات ذات الصلة

PUT /v1/positions/{positionId} تعديل إيقاف الخسارة/جني الأرباح للمركز

يحدّث إيقاف الخسارة و/أو جني الأرباح لمركز مفتوح. يُرجع ExecutionResponse.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`positionId`	path	int64		معرّف المركز

نص الطلب application/json

الحقل	النوع	الوصف
`stopLoss`	double	سعر إيقاف الخسارة الجديد (`null` للإزالة)
`takeProfit`	double	سعر جني الأرباح الجديد (`null` للإزالة)
`trailingStopLoss`	boolean	تفعيل إيقاف الخسارة المتحرك

Example request body

{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}

الاستجابات

200 ExecutionResponse

POST /v1/positions/{positionId}/close إغلاق مركز

يغلق مركزاً مفتوحاً بالكامل أو جزئياً. استخدم قيمة أقل من الحجم الكامل للمركز للإغلاق الجزئي. يُرجع ExecutionResponse.

المعلمات

الاسم	موجود في	النوع	مطلوب	الوصف
`positionId`	path	int64		معرّف المركز

نص الطلب application/json

الحقل	النوع	مطلوب	الوصف
`volume`	int64		الحجم المراد إغلاقه بالسنت

Example – full close (1 lot)

{
  "volume": 10000000
}

الاستجابات

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – هامش غير كافٍ للإغلاق الجزئي

الصفقات ¶

GET /v1/deals الحصول على سجل الصفقات

يُرجع الصفقات المنفذة ضمن نطاق زمني.

المعلمات

الاسم	موجود في	النوع	افتراضي	الوصف
`fromTimestamp`	query	string	–	وقت البدء (ISO-8601)
`toTimestamp`	query	string	–	وقت الانتهاء (ISO-8601)
`maxRows`	query	int32	`50`	الحد الأقصى للصفقات المراد إرجاعها

الاستجابات

200 مصفوفة من كائنات Deal

Response body

[
  {
    "dealId": 11111,
    "orderId": 12345,
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "filledVolume": 10000000,
    "executionPrice": 112345.0,
    "executionTimestamp": 1700000000000,
    "dealStatus": "FILLED",
    "commission": -7.00
  }
]

Deal

الحقل	النوع	الوصف
`dealId`	int64	معرّف الصفقة
`orderId`	int64	الأمر الذي أدى إلى هذه الصفقة
`positionId`	int64	معرّف المركز
`symbolId`	int64	معرف الرمز
`tradeSide`	string	`BUY` أو `SELL`
`volume`	int64	الحجم المطلوب بالسنت
`filledVolume`	int64	الحجم المنفذ بالسنت
`executionPrice`	double	سعر التنفيذ
`executionTimestamp`	int64	وقت التنفيذ (epoch ms)
`dealStatus`	string	الحالة – انظر القيم أدناه
`commission`	double	العمولة المحملة

قيم dealStatus

القيمة	المعنى
`FILLED`	الأمر منفذ بالكامل
`PARTIALLY_FILLED`	تم تنفيذ الأمر جزئيًا
`REJECTED`	مرفوض من قبل خادم التداول
`INTERNALLY_REJECTED`	مرفوض داخلياً قبل الوصول إلى الخادم
`ERROR`	حدث خطأ أثناء التنفيذ
`MISSED`	الأمر فائت (مثل فجوة في السوق)

المخططات { #execution-response-schema } ¶

ExecutionResponse ¶

جميع عمليات وضع الأوامر وتعديلها وإلغائها تُرجع هذا الكائن.

الحقل	النوع	الوصف
`orderId`	int64	معرّف الأمر المتأثر
`positionId`	int64	معرّف المركز المتأثر
`executionType`	string	نوع النتيجة – انظر القيم أدناه
`order`	Order	تفاصيل الأمر (إن وجدت)
`position`	Position	تفاصيل المركز (إن وجدت)
`deal`	Deal	تفاصيل الصفقة (إن وجدت)

قيم executionType

القيمة	المعنى
`ORDER_ACCEPTED`	الأمر المعلق مقبول
`ORDER_FILLED`	الأمر منفذ بالكامل
`ORDER_REPLACED`	الأمر معدّل
`ORDER_CANCELLED`	تم إلغاء الأمر
`ORDER_EXPIRED`	انتهت صلاحية الأمر
`ORDER_REJECTED`	الأمر مرفوض
`ORDER_CANCEL_REJECTED`	طلب الإلغاء مرفوض
`ORDER_PARTIAL_FILL`	تم تنفيذ الأمر جزئيًا
`SWAP`	مبادلة المركز مطبقة
`DEPOSIT`	إيداع في الحساب
`WITHDRAW`	السحب من الحساب
`BONUS_DEPOSIT_WITHDRAW`	إيداع أو سحب المكافأة

حدود المعدل ¶

تفرض البوابة حدود المعدل على مستويات متعددة.

المستوى	الوصف
لكل IP	تحد من إجمالي الطلبات من عنوان IP واحد
لكل مستخدم	تحد من إجمالي الطلبات عبر جميع الحسابات لرمز واحد
لكل حساب	تحد من الطلبات المستهدفة لحساب تداول واحد

تم تجاوز حد المعدل

عند تجاوز حد المعدل، يُرجع API الرمز 429 Too Many Requests مع رأس Retry-After.

معالجة الأخطاء ¶

عند فشل الطلب، يُرجع API استجابة خطأ JSON.

Error response format

{
  "error": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Insufficient free margin for this order",
    "httpStatus": 422,
    "retryAfter": null
  }
}

رموز الخطأ ¶

تعليمة	HTTP	الوصف
`INVALID_REQUEST`	400	معاملات الطلب غير صالحة أو مفقودة
`UNAUTHORIZED`	401	الرمز غير صالح أو منتهي الصلاحية أو مفقود
`TRADING_BAD_VOLUME`	400	الحجم غير صالح (أقل من الحد الأدنى أو يتجاوز المركز)
`NOT_ENOUGH_MONEY`	422	هامش حر غير كافٍ
`SYMBOL_NOT_FOUND`	404	معرّف الرمز غير موجود
`MARKET_CLOSED`	409	السوق للرمز مغلق حالياً
`MAINTENANCE`	503	خادم التداول في وضع الصيانة
`TIMEOUT`	504	خادم التداول لم يستجب في الوقت المحدد
`GATEWAY_RATE_LIMIT`	429	تم تجاوز حد المعدل – انظر رأس `Retry-After`

معالجة حد المعدل

عندما تتلقى استجابة 429، يشير رأس Retry-After وحقل retryAfter إلى عدد الثواني التي يجب عليك الانتظار قبل إرسال الطلب التالي.