من النية إلى الأدلة.

احصل على مفتاح API

curl -X POST https://agenttrail.online/api/v1/accounts \
  -H 'Content-Type: application/json' -d '{}'

تحتوي الاستجابة على account_id وkey_id وapi_key لمرة واحدة. احفظه بشكل آمن. يؤدي إنشاء الحساب وإصدار المفتاح الجديد إلى إنشاء بيانات اعتماد جديدة في كل مكالمة ناجحة؛ فهي ليست إعادة نقاط النهاية. لا يمكن استرداد المفاتيح المفقودة بواسطة خدمة التطوير هذه. قم بإصدار مفاتيح الوكيل ذات النطاق من وحدة التحكم.

1. سجل الدفعة المتوقعة

export AUDIT_KEY='<save the one-time API key securely>'
curl -X POST https://agenttrail.online/api/v1/audit/intents \
  -H "Authorization: Bearer $AUDIT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-stable-intent-reference' \
  -d '{"agent_id":"research-01","network":"xrpl-testnet", "asset":{"type":"native","currency":"XRP"},"expected_amount":"1","recipient":"<recipient classic address>","purpose":"purchase_market_data"}'

المبالغ هي سلاسل عشرية. لا يمكن الخلط بين Testnet وMainnet. الغرض وهوية الوكيل عبارة عن إقرارات، وليست دليلاً على التفويض. يتيح payer_address الاختياري مطابقة المرسل؛ وبدون ذلك، لا يتم التحقق من مطابقة الدافع. استخدم context_hash لسياق المهمة الحساسة.

2. ادفع خارجيًا، ثم أرسل التجزئة

يرسل رمز الدفع الخاص بـ Testnet الخاص بك الدفعة. لا ترسل أبدًا إلى الخدمة بذرة المحفظة أو المفتاح الخاص.

curl -X POST https://agenttrail.online/api/v1/audit/transactions \
  -H "Authorization: Bearer $AUDIT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-stable-payment-reference' \
  -d '{"audit_id":"<audit_id>","network":"xrpl-testnet","tx_hash":"<64-character hash>"}'

الرد 202 يعني أن التحقق معلق. أعد محاولة التدقيق في الكتابة باستخدام نفس مفتاح Idempotency-Key ونص الطلب بعد حدوث أخطاء في النقل. إعادة استخدام مفتاح بجسم مختلف يُرجع 409.

3. تحقق من الحالة، ونزّل التقرير، وتحقق بشكل مستقل

curl -H "Authorization: Bearer $AUDIT_KEY" \
  https://agenttrail.online/api/v1/audit/records/<audit_id>
curl -H "Authorization: Bearer $AUDIT_KEY" \
  https://agenttrail.online/api/v1/audit/records/<audit_id>/report -o audit.json

حالة الدفع وحالة الارتساء منفصلتان. anchor_validated فقط هو الذي يقوم بإنشاء عملية التثبيت الكاملة. قد تكون التقارير التي تم تنزيلها معلقة؛ ومن ثم يجب أن يفشل التحقق المستقل بشكل واضح. استخدم صفحة التحقق محليًا أو قم بتشغيل scripts/verify_report.py من المستودع.

الأخطاء وحدود الدعم

400: إدخال غير صالح أو شبكة خاطئة أو مُصدر معطل. 401: مفتاح غير صالح/تم إبطاله. 403: نطاق غير كاف. 404: سجل غائب أو لا يمكن الوصول إليه. 409: العجز/تعارض المعاملات أو التقرير غير جاهز. 413 : الجسم كبير جدا. 429: تم تجاوز الحصة، أعد المحاولة لاحقًا. 503: التخزين/الموفر غير متوفر؛ أعد المحاولة بأمان.

تفسير الدفع المدعوم: XRP المباشر وأصول RLUSD الممكّنة. تستخدم الدفعات الجزئية الناجحة البيانات الوصفية التي تم تسليمها، وليس المبلغ المطلوب أبدًا. المسارات المعقدة ومعاملات التحويل وعدم الدفع غير مدعومة. تظل مهلات العقدة معلقة وقد تتطلب استرداد المشغل من قائمة انتظار الرسائل الميتة.

حدود الإثبات والخصوصية

التقارير والإعلانات خاصة بحسابك. تكشف البراهين العامة عن التجزئة والحد الأدنى من معلومات الدفعة/الشبكة. تثبت المرساة سلامة السجل المقدم، وليس مطالباته أو تسليمه أو تغطيته لكل دفعة. يستخدم تثبيت النظام الأساسي موقع Testnet مقيدًا مخصصًا وميزانيات صريحة وخطوة تمكين المشغل.