نقاط نهاية API - توثيق API

عنوان URL الأساسي

:الإنتاج https://api.usdtlowfee.com

الاصطلاحات العامة

الوحدات

• sun: 1 TRX = 1,000,000 sun (جميع حقول القيمة تستخدم sun)
• energyValue: وحدات الطاقة (رقم int64)
• durationHours: ساعات (رقم int)

أنواع البيانات

• حقول ID: رقم int64 (معرف snowflake)
• حقول القيمة: رقم int64 (تنتهي بـ *Sun مثل: balanceSun، priceSun)
• حقول الوقت: نص (صيغة ISO8601 UTC مثل: "2025-01-15T10:30:00Z")
• حقول Boolean: true/false

صيغة الاستجابة

• النجاح: { "data": {...}, "meta": {...} } (meta اختياري)
• الخطأ: { "error": { "code": "...", "message": "..." } }

إدارة الحساب

الاستعلام عن رصيد المحفظة ومعلومات المستخدم

GET /v1/wallet/balance

الاستعلام عن الرصيد

الاستعلام عن رصيد المحفظة الحالي

:مثال الاستجابة

{
  "data": {
    "balanceSun": 1000000,
    "frozenSun": 0,
    "totalSun": 1000000
  }
}

GET /v1/users/me

معلومات المستخدم

الاستعلام عن المعلومات الأساسية للمستخدم الحالي

:مثال الاستجابة

{
  "data": {
    "id": 123456,
    "email": "user@example.com",
    "emailVerified": true,
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

إدارة الطلبات

إنشاء طلبات الطاقة والاستعلام عنها

POST /v1/energy/orders

إنشاء طلب

إنشاء طلب تأجير طاقة لعنوان محدد (يدعم حاليًا النوع manual فقط)

:معاملات الطلب

المعامل	النوع	مطلوب	الوصف
type	string	نعم	نوع الطلب، يدعم حاليًا "manual" فقط
data.tronAddress	string	نعم	عنوان TRON الذي سيتلقى الطاقة (34 حرفًا، يبدأ بـ T)
data.energyValue	int64	نعم	كمية الطاقة (رقم، الحد الأدنى 32000، يُنصح بـ 65000 لتحويل USDT)
data.durationHours	int	نعم	مدة التأجير (بالساعات، القيم الصالحة: 1، 24، 72، 168، 336، 720)

:مثال الطلب

{
  "type": "manual",
  "data": {
    "tronAddress": "TYour1Address2Here3...",
    "energyValue": 65000,
    "durationHours": 1
  }
}

:مثال الاستجابة

{
  "data": {
    "id": 1234567890,
    "userId": 9876543210,
    "tronAddress": "TYour1Address2Here3...",
    "energyValue": 65000,
    "durationHours": 1,
    "priceSun": 3000000,
    "priceTrx": 3.0,
    "orderType": "manual",
    "status": "processing",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z",
    "statusUpdatedAt": "2025-01-15T10:30:00Z",
    "canTransitionTo": ["completed", "failed"]
  }
}

GET /v1/energy/orders/:id

الاستعلام عن طلب

الاستعلام عن تفاصيل الطلب حسب المعرّف

:مثال الاستجابة

{
  "data": {
    "id": 1234567890,
    "userId": 9876543210,
    "tronAddress": "TYour1Address2Here3...",
    "energyValue": 65000,
    "durationHours": 1,
    "priceSun": 3000000,
    "priceTrx": 3.0,
    "orderType": "manual",
    "status": "completed",
    "txid": "abc123...",
    "createdAt": "2025-01-15T10:30:00Z",
    "completedAt": "2025-01-15T10:30:05Z",
    "updatedAt": "2025-01-15T10:30:05Z",
    "statusUpdatedAt": "2025-01-15T10:30:05Z",
    "canTransitionTo": []
  }
}

GET /v1/energy/orders

قائمة الطلبات

الاستعلام عن قائمة الطلبات (يدعم الترقيم والفلترة)

:معاملات الطلب

المعامل	النوع	مطلوب	الوصف
offset	number	لا	نقطة البداية، الافتراضي 0
limit	number	لا	عدد العناصر لكل صفحة، الافتراضي 20، الأقصى 100
status	string	لا	الفلترة حسب حالة الطلب: processing، completed، failed

:مثال الاستجابة

{
  "data": {
    "orders": [
      {
        "id": 1234567890,
        "userId": 9876543210,
        "tronAddress": "TYour1...",
        "energyValue": 65000,
        "durationHours": 1,
        "priceSun": 3000000,
        "priceTrx": 3.0,
        "orderType": "manual",
        "status": "completed",
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T10:30:05Z",
        "statusUpdatedAt": "2025-01-15T10:30:05Z",
        "canTransitionTo": []
      }
    ],
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

إدارة العناوين

إدارة العناوين المستخدمة بشكل متكرر

POST /v1/addresses

إضافة عنوان

حفظ عنوان جديد

:مثال الطلب

{
  "tronAddress": "TYour1Address2Here3...",
  "label": "المحفظة الرئيسية",
  "isDefault": false
}

:مثال الاستجابة

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "المحفظة الرئيسية",
    "isDefault": false,
    "usageCount": 0,
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

GET /v1/addresses

قائمة العناوين

الحصول على قائمة العناوين المحفوظة

:مثال الاستجابة

{
  "data": {
    "addresses": [
      {
        "id": 1,
        "tronAddress": "TYour1Address2Here3...",
        "label": "المحفظة الرئيسية",
        "isDefault": true,
        "usageCount": 5,
        "lastUsedAt": "2025-01-15T10:30:00Z",
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /v1/addresses/:id

تفاصيل العنوان

الاستعلام عن معلومات العنوان

:مثال الاستجابة

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "المحفظة الرئيسية",
    "isDefault": true,
    "usageCount": 5,
    "lastUsedAt": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

PUT /v1/addresses/:id/label

تحديث تسمية العنوان

تغيير تسمية العنوان

:مثال الطلب

{
  "label": "تسمية جديدة"
}

:مثال الاستجابة

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "تسمية جديدة",
    "isDefault": false,
    "usageCount": 3,
    "lastUsedAt": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

PUT /v1/addresses/:id/default

تعيين كعنوان افتراضي

تعيين العنوان المحدد كعنوان مستلم افتراضي

:مثال الاستجابة

// HTTP 204 No Content
// لا يوجد محتوى استجابة

يُرجع الحالة 204 بدون محتوى عند النجاح

DELETE /v1/addresses/:id

حذف عنوان

حذف عنوان محفوظ