Credits وعمليات الشحن

استخدم token بصلاحية write لطلب مسودة شحن. اقرأ الحد الأدنى الحالي وأسعار كل أصل والتوفر والمكافأة والحدود القصوى من pricing قبل الدفع. مبلغ المثال هو 10,000 Credits على الأقل ولا يقل أبدًا عن الحد الأدنى المكوَّن لهذه النسخة. الـ Credits مثبّتة بالدولار الأمريكي؛ مبالغ الأصول تُسعَّر وليست ثابتة. المسودة تعليمة دفع، وليست قيدًا للـ Credits.

curl -X POST 'https://ftso.app/api/x402/topup' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: topup_20260930_001' \
  -d '{"credits":10000,"asset":"FBEST"}'
# asset: FBEST | WFLR | FXRP | FLR | XRP

تعيد المسودة عنوان PaymentRouter وasset وamountRaw وdeadline وsignedBy وtypedData وsignature. يستخدم FXRP ستة منازل عشرية؛ لا تتعامل معه كرمز بثمانية عشر منزلة عشرية. تحقق من الـ Router والخزينة (treasury) المتوقعين مقابل التكوين العام، واقرأ settlementSigner() وتحقق تشفيريًا من توقيع EIP-712. مقارنة signedBy وحدها لا تتحقق من توقيع. تأكد من buyer وasset وamount والسلسلة وdeadline وfeeBps=0 وmode=0 قبل الموافقة (approve) واستدعاء pay().

// draft is response.topup; router and token are viem contract instances.
// Verify the complete authorization before approval or payment.
const m = draft.typedData.message;
await token.write.approve([draft.routerAddress, BigInt(draft.amountRaw)]);
const txHash = await router.write.pay([
  { ...m, amount: BigInt(m.amount), deadline: BigInt(m.deadline), nonce: m.nonce },
  draft.signature,
]);

curl -X POST 'https://ftso.app/api/x402/topup/HANDLE/confirm' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"txHash":"0xPAY_TRANSACTION_HASH"}'

يتحقق التأكيد من الدفع قبل إضافة الرصيد. تجزئة المعاملة وحدها ليست دليلًا على شحن مدفوع. ينقل الـ Router المبلغ المصرَّح به؛ التأكيد المكرر لا يمكنه منح الـ Credits مرتين.

أرسل amountWei من المسودة إلى payTo على السلسلة 14، حاملًا مقبض dataHex بحجم 32 بايت بالضبط. لا حاجة إلى موافقة رمز (token approval). ثم أكّد تجزئة المعاملة. تعتمد الـ Credits على القيمة المسلَّمة، مقرَّبة إلى الأدنى ومحدودة بالحدود القصوى المكوَّنة.

await wallet.sendTransaction({
  to: draft.payTo,
  value: BigInt(draft.amountWei),
  data: draft.dataHex,
  chainId: 14,
});

استخدم عنوان XRPL المعاد وdestinationTag مع amountDrops. يخصّص destination tag الدفعة لعملية الشحن الصحيحة. استعلم عن نقطة نهاية الحالة بـ token بصلاحية read؛ يضيف الـ worker الرصيد لدفعة مسلَّمة ومتحقَّق منها بشكل غير متزامن. لا يوجد وقت إكمال مضمون. تصديق FDC الاختياري يأتي بعد إضافة الرصيد ولا يشترطه. قد تبقى verifiedByFdc بقيمة false.

curl 'https://ftso.app/api/x402/topup/HANDLE' \
  -H 'authorization: Bearer fbx_READ_TOKEN'

التزم بموعد deadline الخاص بالمسودة. دفعات FLR/XRP النسبية المتأخرة تستخدم الأدنى من السعر المجمَّد والسعر الحالي؛ وبدون سعر حالي ينتظر الـ worker. تحدّ الحدود القصوى لكل عملية شحن الدفعات الزائدة المضافة إلى الرصيد؛ وتجاوز حد أقصى لحيازات أصل يوقف المسودات الجديدة مؤقتًا. لا ترسل أبدًا بدون أمر الـ Router أو dataHex أو destinationTag: لا يستطيع التطبيق نسب مثل هذه الدفعة بشكل موثوق.

تتطلب مشتريات الاشتراك بـ Bearer مفتاح Idempotency-Key من 8–128 حرفًا أو رقمًا أو شرطة سفلية أو شرطة. الترويسة مدعومة أيضًا لإنشاء watch ومسودات الشحن وإنشاء المستلمين وPUT الخاص بالقنوات. أعد استخدام المفتاح نفسه والـ body نفسه بعد انتهاء المهلة. تُحتفظ الاستجابات النهائية لمدة 24 ساعة؛ الـ body المتغيّر يعيد 409 idempotency_key_reused. الحجز النشط يعيد 409 idempotency_in_progress مع Retry-After. الأخطاء القابلة لإعادة المحاولة تحرّر المفتاح؛ المسودات المنتهية تعيد 410 draft_expired. عمليات الإعادة (replays) تُحتسب ضمن حدود المعدل. قد تكون الأسرار المعادة قابلة للاسترداد عبر إعادة من المحفظة نفسها لمدة 24 ساعة.

تُحاسَب الـ Credits المكتسبة بشكل منفصل عن الـ Credits المشتراة. يستخدم تحويل FBEST القائم طلبًا وموافقة من المسؤول ومطالبة من المحفظة على ConversionVault؛ الدفع الآلي غير مُنفَّذ. راجع Credits لمسار عمل المستخدم.

للأسعار والتوفر والتكوين السارية حاليًا استخدم /api/x402/pricing. يقرأ هذا القسم تكوين نسخة التطبيق هذه؛ ولا يستعلم عن الخزينة أو عن خادم بعيد.

• الحد الأدنى للشحن بالـ Credits: 10000
• دولار أمريكي لكل 1,000 Credit: 1

• FBEST: الحد الأقصى لكل عملية شحن: لا يوجد حد أقصى مكوَّن; عتبة حيازات الخزينة: لا يوجد حد أقصى مكوَّن.
• WFLR: الحد الأقصى لكل عملية شحن: لا يوجد حد أقصى مكوَّن; عتبة حيازات الخزينة: لا يوجد حد أقصى مكوَّن.
• FXRP: الحد الأقصى لكل عملية شحن: 1000; عتبة حيازات الخزينة: 5000.
• FLR: الحد الأقصى لكل عملية شحن: لا يوجد حد أقصى مكوَّن; عتبة حيازات الخزينة: لا يوجد حد أقصى مكوَّن.
• XRP: الحد الأقصى لكل عملية شحن: 1000; عتبة حيازات الخزينة: 5000.