> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AFK API v1

> نظرة عامة والاصطلاحات لواجهة AFK Crypto الإصدار v1

## نظرة عامة

* المسار الأساسي: `/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)

## السلاسل

اطّلع على القائمة الكاملة في [السلاسل المدعومة](/api-reference/supported-chains/). استخدم مُعرّف `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`.

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

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

```json theme={null}
{
  "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` – خطأ الخادم

<Note>
  **تفاصيل 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".
  * هذا سلوك متوقّع عندما يُحدّد الرمز/المِنتة المطلوبة كغير قابلة للتداول من قِبل المزوّد الأعلى، حتى لو كانت هناك مجمّعات موجودة في أماكن أخرى.
</Note>

## التحقق

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

* 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.

## ذات صلة

<CardGroup cols={2}>
  <Card title="السلاسل المدعومة" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="السياسات والأمان" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>