الانتقال إلى المحتوى الرئيسي

​
نظرة عامة

  • المسار الأساسي: /api/v1
  • المصادقة: مفتاح API عبر ترويسة x-api-key
  • خاصية اللاتغيّر: عمليات الكتابة تتطلب ترويسة Idempotency-Key (صيغة UUID)
  • تنسيق الاستجابة: تتضمن جميع الاستجابات ترويسة x-request-id للتتبع

​
الواجهات

  • GET /api/v1/wallets – عرض محافظ المستخدم
  • GET /api/v1/wallets/balances – أرصدة محفظة المتصل (حسب السلسلة؛ تُفضّل المحفظة الافتراضية)
  • GET /api/v1/wallets/:address/balances – أرصدة عنوان محفظة مملوك محدّد
  • GET /api/v1/tx/:id – جلب تفاصيل المعاملة
  • POST /api/v1/send – إرسال الأصول والرموز (EVM + Solana)
  • POST /api/v1/token/approve – موافقة رمز ERC20 (EVM فقط)
  • POST /api/v1/contracts/send – تفاعل عام مع العقود (EVM فقط)
  • POST /api/v1/trade/quote – جلب عروض التبادل (EVM + Solana)
  • POST /api/v1/trade/swap – تنفيذ التبادلات (EVM + Solana)

​
السلاسل

اطّلع على القائمة الكاملة في السلاسل المدعومة. استخدم مُعرّف chain (مثلًا: base، solana-devnet).

​
تحديد المعدّل

  • الكتابة (بما في ذلك POST /api/v1/trade/quote): 15 طلبًا في الدقيقة لكل مستخدم
  • القراءة: 60 طلبًا في الدقيقة لكل مستخدم
  • الاستجابة: HTTP 429 عند التجاوز
  • الترويسات: Retry-After (ثوانٍ حتى النافذة التالية)

​
اللاتغيّر (عمليات الكتابة)

  • جميع الواجهات المُعدّلة تتطلب Idempotency-Key.
  • إعادة استخدام مفتاح مع نفس جسم الطلب يعيد استجابة 200 الأصلية.
  • إعادة استخدام مفتاح مع جسم مختلف تعيد 409 مع code: IDEMPOTENT_BODY_MISMATCH.
  • إعادة استخدام مفتاح دون استجابة نجاح محفوظة تعيد 409 مع code: IDEMPOTENT_REPLAY.
  • المفاتيح مُجالها المستخدم المصادَق؛ يتم تتبّع مسار الواجهة.
  • ينطبق على: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

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

​
تنسيق استجابة الخطأ

{
  "error": "رسالة خطأ قابلة للقراءة",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
رموز الأخطاء

  • UNAUTHORIZED – مصادقة مفقودة/غير صالحة أو مفتاح API (HTTP 401)
  • FORBIDDEN – مُصادَق لكن غير مُصرّح بتنفيذ الإجراء (HTTP 403)
  • NOT_FOUND – المورد غير موجود (HTTP 404)
  • RATE_LIMITED – تجاوز حد المعدل (HTTP 429)
  • INVALID_INPUT – معلمات طلب غير صالحة (HTTP 400)
  • WALLET_NOT_FOUND – المحفظة المحددة غير موجودة
  • USER_NOT_LINKED – المستخدم غير مربوط بـ Privy
  • WALLET_NOT_DELEGATED – المحفظة غير مُفوّضة إلى موقّع الخادم
  • WALLET_ID_REQUIRED – معرف محفظة Privy مفقود
  • CHAIN_UNKNOWN – سلسلة غير معروفة أو غير مدعومة
  • INSUFFICIENT_FUNDS – المُرسل يفتقر إلى الأموال للقيمة/الرسوم
  • IDEMPOTENT_BODY_MISMATCH – جسم طلب مختلف مع نفس مفتاح اللاتغيّر (HTTP 409)
  • IDEMPOTENT_REPLAY – مفتاح اللاتغيّر مُستخدم بالفعل (HTTP 409)
  • PRIVY_RPC_ERROR – خطأ في خدمة Privy RPC
  • SEND_FAILED – فشل إرسال المعاملة
  • SERVICE_UNAVAILABLE – الخدمة المطلوبة غير مُهيّأة
  • QUOTE_FAILED – خطأ في خدمة عروض الأسعار (HTTP 400)
  • INTERNAL_ERROR – خطأ الخادم
تفاصيل QUOTE_FAILED:
  • Solana/Jupiter: بعض مِنَتات Solana غير قابلة للتداول على Jupiter (قائمة بيضاء مُنسّقة). في هذه الحالات، تُعيد واجهة API رمز HTTP 400 مع code: QUOTE_FAILED ورسالة خطأ مثل: “Token not tradable on Jupiter”.
  • EVM/1inch: إذا كان الرمز غير مدعوم بواسطة 1inch، تُعيد واجهة API رمز HTTP 400 مع code: QUOTE_FAILED ورسالة مثل: “Token not tradable on 1inch”.
  • هذا سلوك متوقّع عندما يُحدّد الرمز/المِنتة المطلوبة كغير قابلة للتداول من قِبل المزوّد الأعلى، حتى لو كانت هناك مجمّعات موجودة في أماكن أخرى.

​
التحقق

​
صيغ العناوين

  • EVM: يجب أن يطابق ‎/^0x[a-fA-F0-9]{40}$/‎
  • Solana: يجب أن يكون مفتاحًا عامًا Base58 صالحًا

​
معلمات شائعة

  • المبالغ (EVM): سلاسل عددية صحيحة فقط (عشري أو 0x-hex). يجب أن تكون غير سالبة. بالنسبة لـ ERC20 و value، يجب أن تلائم uint256.
  • المبالغ (Solana): سلاسل عددية صحيحة بوحدات أساسية. يجب أن تلائم مبالغ SPL نطاق 64 بت غير موقّع.
  • المُرسل (from): اختياري. عند عدم التحديد، يُستخدم المحفظة الافتراضية للمستخدم للسلسلة المحددة.
  • اللاتغيّر: جميع واجهات الكتابة تتطلب ترويسة Idempotency-Key. التكرارات مع نفس الجسم تُعيد الاستجابة الأصلية.

​
كلمة مفتاحية للرمز الأصلي

واجهات التداول (/api/v1/trade/quote، /api/v1/trade/swap) تقبل الكلمة المفتاحية NATIVE (غير حساسة لحالة الأحرف) لـ fromToken/toToken:
  • EVM: NATIVE يتم تحليلها إلى 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana: NATIVE يتم تحليلها إلى مِنتة SOL المُغلّفة So11111111111111111111111111111111111111112
  • الاستجابات تُعيد العناوين المُحلّلة (وليس NATIVE)
  • واجهة الإرسال تستخدم asset: "native" بدلًا من عناوين الرموز للتحويلات الأصلية

​
اصطلاحات

  • اختيار السلسلة: استخدم مُعرّف chain (مثلًا: base، base-sepolia، solana-devnet).
  • قيم Transaction.chainId في Solana: ‏0 = الشبكة الرئيسية، ‏-2 = الاختبار، ‏-3 = التطوير.
  • اللاتغيّر: فريد لكل مستخدم ومفتاح؛ التكرارات تعيد الاستجابة الأصلية؛ اختلاف الأجسام → 409.

​
ذات صلة

السلاسل المدعومة

السياسات والأمان