Developers

اقتباس عملية

التسعير هو نقطة النهاية الوحيدة المفتوحة اليوم، والأكثر أهمية: فهو يُرجع التفصيل سطرًا بسطر الذي يعرضه الموقع. لا يتطلب مفتاحًا.

POST/api/quoteLive

اقتباس عملية

يُرجع التفصيل الكامل لعملية البيع: سعر السوق المتوسط المستخدم، كل رسوم في سطر خاص، المبلغ الصافي والسعر الفعلي الذي تم الحصول عليه. مجموع الأسطر يساوي بالضبط الفرق بين الإجمالي والصافي — يتم التحقق من الثبات قبل مغادرة الاستجابة، ولا يتم إرجاع استجابة غير متوازنة أبدًا.

المصادقة: لا شيء اليوم. نقطة نهاية عرض السعر مفتوحة: عرض السعر لا يكشف أي بيانات شخصية.

المعلمات

المعلمات
الحقل	النوع	الوصف
`assetId`مطلوب	string	معرّف الأصل المودَع، على سبيل المثال "btc"، "usdt"، "sol".
`railId`مطلوب	string	معرّف طريقة الدفع، على سبيل المثال "sepa_instant"، "br_pix"، "ke_mpesa".
`networkId`	string	شبكة الإيداع. اختياري: يتم استخدام الشبكة الأولى للأصل افتراضيًا. تختلف تكلفة الشبكة كثيرًا بين الشبكات، لذا يغير هذا الحقل المبلغ الصافي.
`direction`مطلوب	"sell" \| "receive"	اتجاه الإدخال. "sell": المبلغ هو ما تودعه. "receive": المبلغ هو ما تريد استلامه، ويتم تحديد الإيداع المطلوب عن طريق البحث الثنائي.
`amount`مطلوب	string	المبلغ بالوحدات الرئيسية، يُرسل كسلسلة نصية. العدد العشري JSON سيفقد الوحدات الثانوية على المبالغ الكبيرة: السلسلة هي التنسيق الوحيد الذي يتفق عليه العميل والخادم حتى السنت.

الطلبbash

curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "sepa_instant",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'

الاستجابة — مثال حقيقيjson

{
  "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 },
  "gross": "921.68",
  "net": "912.28",
  "currency": "EUR",
  "currencyDecimals": 2,
  "midRate": "0.92168430",
  "effectiveRate": "0.91228000",
  "totalCostBps": 102,
  "lines": [
    { "code": "network", "amount": "1.11", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "8.29", "basis": "0.90 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 1, "p95Minutes": 12 },
  "lockSeconds": 1800,
  "rateAsOf": 1788356981608,
  "rateSource": "mock",
  "limitError": null
}

تحمل الاستجابة Cache-Control: no-store. الاقتباس المخزن هو سعر قديم يُقدَّم كسعر ثابت.
انتهاك حد القناة ليس خطأ HTTP: يتم إرجاع الاقتباس مع كائن limitError يحمل رمز below_min أو above_max والحد الدقيق، بحيث يمكن لواجهتك عرض الرسالة الصحيحة دون استدعاء ثانٍ.
يحدد rateSource من أين جاء السعر. القيمة "mock" هي مصدر التطوير الحتمي: لا يمكن تشغيلها في الإنتاج، حيث ترفض العملية البدء بدلاً من اقتباس أسعار مجمدة.

الأخطاء المحتملة: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. الفهرس الكامل

قراءة التفصيل

مصفوفة lines تحتوي على إدخال واحد لكل رسوم حقيقية. السطر الصفري لا يُرجع: عرض «رسوم الشبكة: 0.00» لا يضيف شيئًا ويزحم الواجهة.

قراءة التفصيل
code	من يستلمها	ما هي
`network`	شبكة البلوكشين	تكلفة نقل الأصل، تُخصم عينًا من الإيداع قبل التحويل. تختلف حسب الشبكة المختارة، أحيانًا بعامل كبير: لهذا يغيّر networkId المبلغ الصافي.
`spread`	نحن	هامش ربحنا، معبَّر عنه كنسبة مئوية من المبلغ المحوَّل. هو السطر الوحيد الذي يمثل إيرادنا.
`rail`	مؤسسة الدفع	رسوم طريقة الدفع، ثابتة أو نسبية أو كلاهما. غائبة عندما لا تفرض الشبكة رسومًا، وهو الحال لمعظم الشبكات المفتوحة.
`fx`	صرف العملات	سطر مخصص لفارق صرف صريح عند حدوث تحويل إضافي. لا يظهر في الممرات حيث تكون عملة الشبكة هي عملة التسعير.

الثابت الذي يجعل الجدول قابلًا للتحقق

الإجمالي ناقص مجموع الأسطر يساوي الصافي تمامًا، حتى أصغر وحدة. يتم التحقق من هذه المساواة في كل تسعيرة قبل مغادرة الاستجابة؛ إذا لم تتوازن، فهناك هامش غير معلن في مكان ما، ويُطلق المحرك خطأً بدلاً من إرجاعها. يمكنك إعادة الحساب: هذا هو الهدف.

مثال مع رسوم التحويل

نفس المبلغ نحو شبكة تحويل تفرض رسومًا على الإرسال يُظهر السطر الثالث. استجابة حقيقية، تم الحصول عليها من مصدر التطوير الحتمي.

طلبbash

curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "ke_mpesa",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'

الاستجابة — مثال حقيقيjson

{
  "gross": "129525.90",
  "net": "128141.44",
  "currency": "KES",
  "totalCostBps": 107,
  "lines": [
    { "code": "network", "amount": "155.44", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "582.17", "basis": "0.45 % du montant converti" },
    { "code": "rail",    "amount": "646.85", "basis": "0.50 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 2, "p95Minutes": 45 },
  "limitError": null
}

ثلاثة أسطر، ثلاثة مستلمين مختلفين: الشبكة، نحن، مؤسسة الدفع. حقل totalCostBps يعطي الفجوة الإجمالية من سعر منتصف السوق بالنقاط الأساسية — الرقم الوحيد الذي يستحق المقارنة بين الخدمات، لأنه يغطي كل شيء، بما في ذلك ما قد يختبئ داخل السعر.

حدود التحويل

المبلغ خارج حدود التحويل لا ينتج خطأ HTTP: يتم إرجاع عرض السعر، مع كائن limitError. لذلك يمكن لواجهتك عرض المبلغ والسبب الدقيق، دون استدعاء ثانٍ.

مقتطف من الاستجابة — مثال حقيقيjson

{
  "net": "3.47",
  "currency": "EUR",
  "limitError": { "code": "below_min", "limit": "20.00" }
}

القيم الممكنة هي below_min و above_max، و limit يحمل الحد بالوحدات الرئيسية لعملة التحويل. ملاحظة: الحد ينطبق على المبلغ الصافي، وليس الإيداع — ما يستلمه المستفيد هو ما يجب أن يتوافق مع حدود التحويل.

نافذة الصلاحية

حقل lockSeconds يوضح المدة التي سيتم خلالها تجميد السعر بمجرد إنشاء الأمر. يعتمد على الأصل: أطول على العملة المستقرة، وأقصر على العملة المتقلبة.

عرض السعر نفسه ليس نهائيًا: إنه استرشادي حتى يتم إنشاء أمر. يتم تثبيت السعر عند إنشاء الأمر، وليس عند استدعاء عرض السعر.
النافذة تغطي قرارك، وليس وقت تأكيد الشبكة. قد يحتاج إيداع البيتكوين إلى ساعة من التأكيدات: التثبيت يحمي من تحركات السوق بينما تقرر وتودع.
إذا وصل الإيداع بعد انتهاء الصلاحية، يتم إعادة تسعير الأمر ويجب قبول المبلغ الجديد. إعادة تسعير صامتة ضد العميل مستحيلة بطبيعتها.
لا تقم بتخزين عرض سعر مؤقتًا لتغطية خطأ سعر قديم. عرض السعر المخزن مؤقتًا هو سعر قديم يُعرض على أنه نهائي، وهو بالضبط المشكلة التي يمنعها رمز الرفض.