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

# TypeScript SDK

> @raydium-io/raydium-sdk-v2 من البداية إلى النهاية — التثبيت، واجهات الوحدات الأربع، بناء المعاملات، والأخطاء الشائعة التي تواجه كل متكامل جديد.

<Info>
  **هذه الصفحة مُترجَمة آليًا بواسطة الذكاء الاصطناعي. النسخة الإنجليزية هي المرجع المعتمد.**

  [عرض النسخة الإنجليزية →](/sdk-api/typescript-sdk)
</Info>

<Info>
  **لافتة الإصدار.** تتناول هذه الصفحة `@raydium-io/raydium-sdk-v2@0.2.42-alpha`، وهو الإصدار المُتحقَّق من كل عرض توضيحي للكود في هذا الموقع (2026-04). SDK في مرحلة ما قبل 1.0 وتطورت سطح الأنواع عبر الإصدارات — قم بتثبيت إصدار محدد.
</Info>

## التثبيت

```bash theme={null}
npm install @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
# أو
pnpm add @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
```

SDK مكتوب بلغة TypeScript ويرسل `.d.ts` بجانب artifact JS الخاص به. أدنى مجموعة أدوات: Node 18+، TypeScript 5.0+، `moduleResolution: "bundler"` أو `"node16"`.

## التهيئة

نقطة الدخول هي `Raydium.load`:

```ts theme={null}
import { Raydium } from "@raydium-io/raydium-sdk-v2";
import { Connection, Keypair, clusterApiUrl } from "@solana/web3.js";

const connection = new Connection(process.env.RPC_URL ?? clusterApiUrl("mainnet-beta"));
const owner      = Keypair.fromSecretKey(/* ... */);

const raydium = await Raydium.load({
  owner,
  connection,
  cluster: "mainnet",           // "mainnet" | "devnet"
  disableFeatureCheck: true,    // تخطي استدعاء API الكشف عن الميزات عند بدء التشغيل
  blockhashCommitment: "confirmed",
});
```

`Raydium.load` غير متزامن لأنه يجلب حمولة `/config` صغيرة من `api-v3.raydium.io` عند بدء التشغيل (حيث يتم سرد حسابات `AmmConfig` الحالية وفئات الرسوم وما إلى ذلك). عيّن `disableFeatureCheck: true` في البيئات غير المتصلة؛ سيتعين عليك توفير تلك القيم يدويًا لبعض المنشئين.

## واجهات الوحدات الأربع

بمجرد التحميل، يكشف الكائن `raydium` عن أربع واجهات وحدات، واحدة لكل سطح منتج:

```ts theme={null}
raydium.cpmm       // تجمعات CPMM: createPool, addLiquidity, withdrawLiquidity, swap, ...
raydium.clmm       // تجمعات CLMM: createPool, openPositionFromBase, increasePositionFromBase,
                   //             decreaseLiquidity, harvestAllRewards, swap, ...
raydium.liquidity  // تجمعات AMM v4: computeAmountOut, swap, addLiquidity, removeLiquidity, ...
raydium.farm       // Farm v3/v5/v6: deposit, withdraw, harvestAllRewards, create, setRewards
raydium.launchpad  // LaunchLab: createLaunchpad, buyExactIn, sellExactIn, graduate, ...
raydium.trade      // توجيه متعدد التجمعات: quotes, route-execution (beta في 0.2.41)
raydium.token      // أدوات مساعدة: الحصول على قائمة الرموز والبيانات الوصفية وإنشاء ATA
```

(نعم، خمس واجهات إجمالاً — "أربع" هي الطريقة التي يجمع بها Raydium بينها علنًا، مع `trade` و `token` كأدوات دعم مساعدة.)

## منشئو المعاملات

تُرجع كل دالة طفرة منشئًا بدلاً من التنفيذ الفوري:

```ts theme={null}
const { execute, builder, transaction, innerTransactions, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    amountInA,
    amountInB,
    slippage: 0.005,
    txVersion: TxVersion.V0,
  });
```

الحقول المُرجَعة:

* **`execute`** — دالة راحة توقّع وترسل. مكافئة لـ `builder.execute`.
* **`builder`** — مثيل `TxBuilder` مع جميع التعليمات والموقِّعين المتراكمة. استدع `.build()` للحصول على `VersionedTransaction[]`؛ مفيد عندما تحتاج إلى إدراج تعليماتك الخاصة أو التوقيع باستخدام موقِّعين خارجيين.
* **`transaction` / `innerTransactions`** — مصفوفات التعليمات الخام. استخدم عند بناء معاملات متعددة البرامج المركبة.
* **`extInfo`** — إضافات خاصة بالمنتج. على سبيل المثال، `createPool` ترجع `extInfo.poolId`؛ `createLaunchpad` ترجع PDA حالة الإطلاق الجديدة.

`txVersion` يتحكم في صيغة المعاملات القديمة مقابل V0. يُوصى افتراضيًا بـ V0 (جداول البحث عن ال주소) — فهو يسمح بدخول swaps أكبر في معاملة واحدة.

### لماذا منشئو غير متزامنين؟

يجلب كل منشئ داخليًا حالة on-chain تقريبًا: معلومات المجموعة (للاقتباسات)، ملكية برنامج الرموز (لـ Token-2022 مقابل توجيه SPL)، إعفاء الإيجار للحساب (لإنشاء ATA)، وما إلى ذلك. SDK يخزن مؤقتًا بعدوانية لكن الاستدعاء الأول لمجموعة جديدة يتضمن جولات RPC. احتفظ بمثيل `raydium` طويل المدى لتجنب إعادة الجلب.

## إضافات وحدة CLMM (أحدث إصدار)

اكتسبت واجهة CLMM أسطحًا للميزات الجديدة للرسوم الديناميكية والرسوم أحادية الجانب وأوامر الحدود:

* **`raydium.clmm.createCustomizablePool`** — مجموعة فائقة من `createPool` التي تقبل `collectFeeOn` و `enableDynamicFee` و `dynamicFeeConfigId`. استخدم هذا لأي مجموعة جديدة تحتاج إلى الأزرار الجديدة؛ يستمر `createPool` الكلاسيكي في العمل للمجموعات الافتراضية الرسوم.
* **`raydium.clmm.openLimitOrder`** — فتح أمر حد على علامة واحدة في مجموعة تدعمها. يأخذ `poolInfo` و `poolKeys` و `limitOrderConfig` (من `/main/clmm-limit-order-config`) و `inputMint` و `inputAmount` والـ `tick` المستهدف.
* **`raydium.clmm.increaseLimitOrder` / `decreaseLimitOrder`** — اضبط الجزء غير المملوء من أمر موجود. الانخفاض ينعكس في أمر مملوء بالكامل مع `InvalidOrderPhase`.
* **`raydium.clmm.settleLimitOrder` / `settleAllLimitOrder`** — اكسح المخرجات المملوءة إلى ATA المالك. يمكن لمالك الأمر أو حارس `limit_order_admin` للمجموعة استدعاؤها.
* **`raydium.clmm.closeLimitOrder` / `closeAllLimitOrder`** — أغلق الأوامر المستقرة بالكامل لاسترجاع الإيجار.
* **`raydium.api.getClmmDynamicConfigs()` / `getClmmLimitOrderConfigs()`** — مساعدات REST التي تضرب نقاط النهاية الجديدة `/main/clmm-dynamic-config` و `/main/clmm-limit-order-config`.

أيضًا نقل إعادة تنظيم صغيرة `utils/` إلى `libraries/`. يجب على الكود الذي استورد من `@raydium-io/raydium-sdk-v2/utils/...` الانتقال إلى `@raydium-io/raydium-sdk-v2/libraries/...`. برميل الحزمة على المستوى الأعلى لم يتغير، لذا لا يرى معظم المستخدمين إعادة التسمية أبدًا.

تُوجد الشروح التفصيلية من البداية إلى النهاية في TypeScript في [`products/clmm/code-demos`](/ar/products/clmm/code-demos).

## الأخطاء الشائعة

### 1. عدم تطابق العنقود

تكوين بدء SDK الخاص بـ SDK خاص بالعنقود. خلط `cluster: "mainnet"` مع `Connection` devnet يسبب توجيهًا صامتًا خاطئًا: SDK يقتبس ضد mainnet `AmmConfig` لكنه يرسل إلى devnet. مرر الاثنين دائمًا.

### 2. نسيان إنشاء ATAs مسبقًا

عند أول تفاعل مع mint، قد لا يكون Associated Token Account للمستخدم موجودًا. SDK يُسبق تلقائيًا تعليمات `AssociatedTokenAccount::create` عندما يكتشف ATA مفقودًا، مما يكلف قدرًا صغيرًا من الإيجار. إذا كان محفظتك منخفضة على SOL سيفشل بصمت. تحقق وموّل قبل إعادة المحاولة.

### 3. `poolInfo` قديم

`poolInfo` لقطة مخزنة مؤقتًا. إذا تغيرت حالة المجموعة منذ جلبتها (حركة كبيرة حركت السعر، على سبيل المثال)، قد يتم حساب `minAmountOut` للـ swap مقابل الحالة القديمة والهبوط تحت المبلغ على السلسلة، مما يعكس. أعد جلب `poolInfo` فورًا قبل بناء المعاملات عالية القيمة، أو استخدم `computeAmountOut` الخاص بـ SDK الذي يعيد الاستعلام عن الاحتياطيات.

### 4. رسوم الأولوية

SDK لا يضيف أسعار وحدات الحساب افتراضيًا. في نوافذ الحجم العالي (إطلاقات المجموعات الجديدة وأحداث العملات المسخرة) هذا يعني أن معاملتك تتنافس مع أخرى كثيرة وقد لا تهبط. وفّر `computeBudgetConfig` صريح:

```ts theme={null}
const { execute } = await raydium.cpmm.swap({
  poolInfo,
  inputAmount: new BN(...),
  swapResult: ...,
  slippage: 0.005,
  txVersion: TxVersion.V0,
  computeBudgetConfig: {
    units: 250_000,          // حد CU
    microLamports: 50_000,   // رسم الأولوية لكل CU
  },
});
```

انظر [`integration-guides/priority-fee-tuning`](/ar/integration-guides/priority-fee-tuning) لإرشادات التحديد.

### 5. تحمل الانزلاق يجب أن يطابق نوع المجموعة

CPMM و AMM v4 هي رياضيات CPMM (تأثير منخفض على التداولات العادية). CLMM متعددة الأجزاء (التأثير يقفز عند عبور التسميات). إذا نسخت تحمل انزلاق 0.5٪ من مثال CPMM إلى swap CLMM يعبر عدة علامات، فمن المحتمل أن تنعكس المعاملة. `computeAmountOut` الخاص بـ SDK يُرجع `priceImpact`؛ حجم تحملك فوقه.

### 6. `BN` مقابل `number`

جميع حقول المبلغ في SDK هي نسخ `BN` من `bn.js` — أبدًا JavaScript `number`. تحويل قيم المبلغ عبر `.toNumber()` يُقطع صامتًا عند `2^53`؛ لأي قيمة فوق \~9 مليار مليار (ليس نادرًا على mints 9-عشري)، هذا ينتج النتيجة الخاطئة. احتفظ بكل شيء في `BN` حتى عرض الواجهة الأمامية النهائي.

## سياسة الإصدارات

* `@raydium-io/raydium-sdk-v2` هو SDK الوحيد الذي يحتفظ به Raydium. جميع الوثائق والعروض التوضيحية وإرشادات التكامل تستهدفه.
* حزمة v1 أقدم (`@raydium-io/raydium-sdk`) موجودة على npm لأسباب تاريخية. انتهت الصيانة بعد شحن CPMM و LaunchLab (v1 لم تحصل أبدًا على الدعم لكليهما)، ولم تكن هناك إصدارات v1 منذ 2024. اعتبر v1 انتهى من العمل: لا تستخدمه للكود الجديد، وهاجر أي عمليات تكامل v1 المتبقية إلى v2.
* SDK v2 في مرحلة ما قبل 1.0. التغييرات الكسرية بين الإصدارات الثانوية 0.x ممكنة؛ ثبّت الإصدار الذي تحققت منه واطّلع على ملاحظات إصدار GitHub عند الترقية.

## الترقية

عند الترقية بين الإصدارات الثانوية للـ SDK:

1. أعد فحص نوع الإرجاع لكل استدعاء طفرة — تغييرات الشكل (على سبيل المثال، `extInfo`) تهبط بشكل متكرر.
2. أعد إنشاء توقيعات جلب `poolInfo` — قد تم إعادة تسمية حقل.
3. أعد التحقق من معالجة الانزلاق الخاصة بك؛ تحول SDK بين السلوك المحدود تلقائيًا والسلوك المحدود اختياريًا عبر الإصدارات.
4. إذا كنت تستخدم `raydium.trade` (التوجيه)، أعد التحقق من شكل المسار — فهو الجزء الأقل استقرارًا من السطح.

## الحصول على المساعدة

لأسئلة SDK و API:

* **مشاكل GitHub** — أرسل إلى [github.com/raydium-io/raydium-sdk-V2/issues](https://github.com/raydium-io/raydium-sdk-V2/issues) للأخطاء والطلبات الميزة. فريق Raydium يراقب بنشاط.
* **Discord** — قناة `#dev-support` في [discord.gg/raydium](https://discord.gg/raydium) للمساعدة المتزامنة.
* **Telegram** — دردشة المطورين المرتبطة من [raydium.io](https://raydium.io) (تجنب مجموعات Telegram غير المتحقق منها).

لمسائل الأمان، **لا** تنشر في القنوات العامة — انظر [`security/disclosure`](/ar/security/disclosure).

## مؤشرات

* [`sdk-api/rest-api`](/ar/sdk-api/rest-api) — المكمل HTTP للـ SDK.
* [`sdk-api/trade-api`](/ar/sdk-api/trade-api) — معاملات swap المدمجة على الخادم.
* [`sdk-api/anchor-idl`](/ar/sdk-api/anchor-idl) — إعادة تطبيقات التوليد مباشرة من IDLs البرنامج.
* [`sdk-api/python-integration`](/ar/sdk-api/python-integration) — المكافئ Python عبر `solana-py`.
* [`integration-guides/priority-fee-tuning`](/ar/integration-guides/priority-fee-tuning) — تحديد حجم `computeBudgetConfig`.

المصادر:

* [Raydium SDK v2 source](https://github.com/raydium-io/raydium-sdk-V2)
* ملاحظات إصدار Raydium SDK.