دليل المطور الشامل لاستخدام Alchemy API: دليل Web3 الكامل

تشغيل تطبيق لامركزي (dApp) لـ Ethereum في مرحلة الإنتاج بدون مزود عقدة موثوق به هو طريق قصير إلى مشاكل الدعم الفني. تتأخر عقد Geth المستضافة ذاتيًا، وتفوت إعادة التنظيم، وتتعطل بمجرد أن يحقق تطبيقك نجاحًا. يصلح واجهة برمجة تطبيقات Alchemy ذلك من خلال توفير طبقة عقدة معززة بالإضافة إلى مجموعة من واجهات برمجة التطبيقات المحسنة التي لم تحددها مواصفات JSON-RPC الخام أبدًا، مثل الحصول على كل NFT في محفظة بمكالمة واحدة بدلاً من مسح كل كتلة منذ الإنشاء.

يرشدك هذا الدليل عبر جميع جوانب واجهة برمجة تطبيقات Alchemy: إنشاء تطبيق، المصادقة، استدعاء طرق JSON-RPC القياسية، استخدام نقاط النهاية المحسّنة، الاشتراك في المعاملات المعلقة عبر WebSocket، وشحن الحسابات الذكية مع رعاية رسوم الغاز من خلال Account Kit. سترى أمثلة لـ curl و Node لكل تدفق رئيسي، وستفهم كيف ترتبط وحدات الحساب (CU) بفاتورتك الشهرية قبل الإطلاق.

إذا كنت تقوم بتقييم البنية التحتية للمحفظة وweb3 بشكل أوسع، فإن Apidog يساعدك على اختبار كل نقطة نهاية في مكان واحد. راجع أيضًا دليلنا حول أفضل واجهة برمجة تطبيقات لمحفظة العملات المشفرة للحصول على رؤية أوسع للسوق قبل الالتزام بمزود.

ملخص سريع (TL;DR)

• تغطي Alchemy شبكات Ethereum و Polygon و Arbitrum و Optimism و Base و Solana و zkSync و Starknet والمزيد من لوحة تحكم واحدة.
• يحصل كل تطبيق على نقاط نهاية HTTPS و WebSocket لـ JSON-RPC القياسي بالإضافة إلى واجهات برمجة تطبيقات محسنة مثل alchemy_getAssetTransfers و alchemy_getTokenBalances و getNFTs.
• تغلف حزمة SDK من Alchemy للغة JavaScript (alchemy-sdk) مكتبة ethers.js وتضيف مساعدين مكتوبين لكل نقطة نهاية محسّنة.
• يوفر Account Kit حسابات ذكية متوافقة مع ERC-4337 مع رعاية رسوم الغاز ومفاتيح الجلسة ومصادقة مفتاح المرور عبر Gas Manager.
• يتم قياس الاستخدام بوحدات الحساب؛ توفر لك الطبقة المجانية 300 مليون وحدة حساب شهريًا، وطبقة النمو 400 مليون وحدة حساب بالإضافة إلى الرسوم الإضافية، وطبقة Scale مخصصة.
• قيود المعدل لكل تطبيق ولكل طريقة؛ تحافظ طلبات الدفعة الواحدة والميزة المدمجة لإعادة المحاولة في SDK على عدم تجاوز حدود التقييد.

ما هي واجهة برمجة تطبيقات Alchemy؟

Alchemy هي منصة للمطورين في web3 تدير عقد blockchain مُدارة وتضيف فوقها محرك فهرسة بيانات. تحصل على ثلاثة أشياء لا يمكنك بناؤها بسهولة بنفسك: عقد JSON-RPC عالية التوافر عبر أكثر من 40 سلسلة، وواجهات برمجة تطبيقات محسنة تفهرس مسبقًا التحويلات وبيانات NFT الوصفية، ومجموعة تجريد للحساب (Account Kit) لتجربة مستخدم بدون رسوم غاز.

بينما توفر Infura لك غالبًا وصولاً خامًا إلى العقدة، تضيف Alchemy طبقة الفهرسة. يستغرق جلب كل تحويل ERC-20 لعنوان واحد استدعاء alchemy_getAssetTransfers واحدًا؛ نفس الاستعلام على عقدة عادية يعني التكرار عبر كل كتلة. هذا هو السبب في أن معظم المحافظ الإنتاجية ولوحات تحكم DeFi وأسواق NFT تستخدم Alchemy للمسارات التي تتطلب قراءة مكثفة.

المصادقة والإعداد

أنشئ حسابًا في لوحة تحكم Alchemy، ثم انقر على إنشاء تطبيق جديد. اختر سلسلة (شبكة Ethereum الرئيسية، Polygon، Base، إلخ) وشبكة (الشبكة الرئيسية أو شبكة اختبار مثل Sepolia). يحصل كل تطبيق على مفتاح API فريد يشكل الجزء الأخير من مسار عنوان URL الخاص بك.

نقطة نهاية HTTPS الخاصة بك تبدو كالتالي:

https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

نقطة نهاية WebSocket الخاصة بك:

wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

تعامل مع مفتاح API كسر سري. ضعه في متغير بيئة، ولا تضعه أبدًا في كود العميل. بالنسبة لتطبيقات dApps في المتصفح، استخدم قوائم السماح (قيود المرجع) في لوحة تحكم Alchemy حتى لا يتمكن مفتاح مسرب من استنزاف حصتك من نطاق مهاجم.

قم بتثبيت SDK:

npm install alchemy-sdk

ثم قم بتهيئة العميل:

import { Alchemy, Network } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

const block = await alchemy.core.getBlockNumber();
console.log("Latest block:", block);

نقاط النهاية الأساسية

JSON-RPC القياسي عبر HTTPS

تعمل أي طريقة JSON-RPC قياسية لـ Ethereum. إليك eth_getBalance باستخدام curl:

curl https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBalance",
    "params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"],
    "id":1
  }'

تعيد الاستجابة الرصيد بالـ wei كسلسلة سداسية عشرية. يعمل نفس النمط مع eth_call و eth_sendRawTransaction و eth_getLogs وكل طريقة قياسية أخرى.

API المحسّنة: getAssetTransfers

تعيد alchemy_getAssetTransfers كل تحويل ETH و ERC-20 و ERC-721 و ERC-1155 والتحويلات الداخلية والخارجية لعنوان معين عبر نطاق من الكتل. مكالمة واحدة تحل محل آلاف استعلامات eth_getLogs.

import { Alchemy, Network, AssetTransfersCategory } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

const transfers = await alchemy.core.getAssetTransfers({
  fromBlock: "0x0",
  toAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  category: [
    AssetTransfersCategory.EXTERNAL,
    AssetTransfersCategory.ERC20,
    AssetTransfersCategory.ERC721,
  ],
  maxCount: 100,
});

for (const t of transfers.transfers) {
  console.log(`${t.asset} ${t.value} from ${t.from} to ${t.to}`);
}

API المحسّنة: getTokenBalances و getNfts

يتطلب الحصول على كل رمز مميز (توكن) تحتفظ به المحفظة، دون معرفة عناوين العقود مسبقًا، مكالمة واحدة:

const balances = await alchemy.core.getTokenBalances(
  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
);

for (const token of balances.tokenBalances) {
  const meta = await alchemy.core.getTokenMetadata(token.contractAddress);
  console.log(`${meta.symbol}: ${token.tokenBalance}`);
}

بالنسبة لـ NFTs، استخدم مساحة الاسم NFT:

const nfts = await alchemy.nft.getNftsForOwner(
  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
);
console.log(`Owns ${nfts.totalCount} NFTs`);

واجهة برمجة التطبيقات للاشتراك عبر WebSocket

تدفع واجهة برمجة تطبيقات الاشتراك التحديثات بدلاً من أن تجعلك تستعلم باستمرار. اشترك في المعاملات المعلقة أو نشاط العنوان:

import { Alchemy, Network, AlchemySubscription } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

alchemy.ws.on(
  {
    method: AlchemySubscription.PENDING_TRANSACTIONS,
    toAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  },
  (tx) => console.log("Pending USDC tx:", tx.hash)
);

هكذا تحافظ روبوتات mempool ومراقبو MEV وواجهات مستخدم محافظ الوقت الفعلي على التحديث دون استهلاك وحدات الحساب (CU) في استعلامات eth_blockNumber.

Account Kit و Gas Manager

Account Kit هو مكدس الحسابات الذكية من Alchemy. يوفر React SDK، وتنفيذ حساب عقد ذكي (Light Account و Modular Account)، و Gas Manager لرعاية عمليات المستخدم. يقوم المستخدمون بالتسجيل باستخدام مفتاح مرور أو بريد إلكتروني، ويحصلون على محفظة ذكية، ولا يلمسون عبارة استعادة أو رمز غاز أبدًا.

import { createLightAccountClient } from "@account-kit/smart-contracts";
import { alchemy, sepolia } from "@account-kit/infra";

const client = createLightAccountClient({
  transport: alchemy({ apiKey: process.env.ALCHEMY_API_KEY }),
  chain: sepolia,
  signer: yourSigner,
});

const { hash } = await client.sendUserOperation({
  uo: { target: "0x...", data: "0x", value: 0n },
});

لتدفقات الإعداد التي تجمع بين الحسابات الذكية والمحافظ المضمنة، راجع دليلنا حول واجهة برمجة تطبيقات Privy، والذي يكمل Account Kit بشكل جيد لتطبيقات dApps الاستهلاكية.

الأخطاء الشائعة وحدود المعدل

تقيس Alchemy الاستخدام بوحدات الحساب (CU). لكل طريقة تكلفة بوحدة الحساب: eth_call تكلف 26 CU، و eth_getLogs تكلف 75، و alchemy_getAssetTransfers تكلف 150، و eth_getBlockByNumber تكلف 16. توفر الطبقة المجانية 300 مليون CU شهريًا وحدًا أقصى للإنتاجية في الثانية.

الأخطاء التي ستراها غالبًا:

• 429 عدد كبير جدًا من الطلبات: لقد تجاوزت الحد الأقصى لوحدات الحساب في الثانية. قم بالتراجع وأعد المحاولة؛ تعالج حزمة SDK هذا تلقائيًا.
• 403 محظور: قائمة السماح لمفتاح API الخاص بك لا تتطابق مع المرجع، أو المفتاح معطل.
• -32600 طلب غير صالح: نص JSON-RPC مشوه. تحقق من اسم الطريقة ومصفوفة المعلمات.
• -32000 تم التراجع عن التنفيذ: تم التراجع عن استدعاء العقد الذكي. قم بفك تشفير سبب التراجع باستخدام eth_call وأداة محاكاة.

طلبات الدفعة الواحدة هي صديقتك. أرسل ما يصل إلى 1000 مكالمة JSON-RPC في طلب HTTP POST واحد، مما يخفف من حمل الشبكة الزائد وغالبًا ما يكلف عددًا أقل من وحدات الحساب الإجمالية. لتدفقات عمل الاختبار الأوسع، يغطي اختبار API بدون Postman في عام 2026 كيفية إدارة مكالمات JSON-RPC المجمعة في مجموعة.

تسعير Alchemy

لدى Alchemy أربع طبقات تسعير عامة:

• مجانية: 300 مليون CU شهريًا، تطبيق واحد، دعم المجتمع. جيدة للنماذج الأولية والمشاريع الشخصية الصغيرة.
• النمو: 49 دولارًا أمريكيًا شهريًا كحد أدنى، تتضمن 400 مليون CU، تفرض رسومًا إضافية لكل CU، تحليلات متقدمة.
• المقياس: 289 دولارًا أمريكيًا شهريًا، 1.5 مليار CU، إنتاجية مخصصة، دعم ذو أولوية.
• المؤسسات: تسعير مخصص، اتفاقيات مستوى الخدمة (SLAs)، عقد خاصة، هندسة حلول مخصصة.

يتم إعادة تعيين وحدات الحساب شهريًا. إذا تجاوزت الحدود في طبقات النمو أو المقياس، فستدفع رسومًا إضافية؛ في الطبقة المجانية، ستبدأ الطلبات بالفشل برمز 429 حتى الدورة التالية. راقب الاستخدام يوميًا في لوحة التحكم خلال شهرك الأول لتتمكن من تحديد الطبقة المناسبة.

اختبار واجهة برمجة تطبيقات Alchemy باستخدام Apidog

تصحيح أخطاء JSON-RPC يدويًا أمر مؤلم. كل طلب هو POST مع مصفوفة معلمات متداخلة، والاستجابات مشفرة سداسيًا، واشتراكات WebSocket يصعب فحصها في طرفية عادية. يوفر لك Apidog مساحة عمل موحدة لحركة مرور REST و GraphQL و WebSocket، بحيث يمكنك الوصول إلى نقاط نهاية Alchemy HTTPS، وفتح WebSocket إلى wss://eth-mainnet.g.alchemy.com/v2/...، ومشاهدة اشتراكات المعاملات المعلقة تتدفق جنبًا إلى جنب.

احفظ مفتاح API الخاص بك كمتغير بيئة في Apidog وأعد استخدامه عبر المجموعات لشبكات mainnet و Sepolia و Polygon و Base. قم ببرمجة تأكيدات على حقول الاستجابة لاكتشاف التراجعات عندما تطرح Alchemy نقاط نهاية محسّنة جديدة. قم بتنزيل Apidog واستورد مواصفات Alchemy OpenAPI لتشكيل مجموعتك في أقل من دقيقة.

الأسئلة الشائعة

هل Alchemy مجانية للاستخدام في مرحلة الإنتاج؟ نعم، ضمن 300 مليون CU شهريًا. العديد من تطبيقات dApps الصغيرة تبقى على الخطة المجانية إلى أجل غير مسمى. بمجرد تجاوز هذا الحد الأقصى أو الحاجة إلى إنتاجية أعلى، فإن خطة النمو بسعر 49 دولارًا هي الخطوة التالية المعتادة.

هل تدعم Alchemy شبكة Solana؟ نعم. تدعم Alchemy شبكتي Solana الرئيسية والتطويرية (devnet) باستخدام طرق Solana RPC القياسية بالإضافة إلى نقاط نهاية محسّنة لبيانات التوكنات وNFTs. أنشئ تطبيق Solana في لوحة التحكم للحصول على نقطة نهاية مخصصة.

هل يمكنني استخدام واجهة برمجة تطبيقات Alchemy بدون SDK؟ بالتأكيد. يمكن استدعاء كل نقطة نهاية عبر HTTPS باستخدام curl أو fetch أو أي عميل HTTP. SDK هو غلاف تسهيل؛ يضيف مساعدين مكتوبين، وإعادة محاولة تلقائية، وإعادة اتصال WebSocket، ولكنه اختياري.

ما الفرق بين Alchemy وواجهات برمجة تطبيقات المطورين في MetaMask؟ تركز MetaMask على تجربة مستخدم المحفظة والتوقيع؛ تركز Alchemy على البنية التحتية للعقد والبيانات. إنهما يحلان مشاكل مختلفة. راجع دليلنا حول واجهة برمجة تطبيقات MetaMask لجانب المحفظة.

كيف أقوم بتدوير مفتاح Alchemy API؟ أنشئ تطبيقًا جديدًا في لوحة التحكم، وحدث بيئتك، وانشر، ثم احذف التطبيق القديم. لا يوجد تدوير فوري، لذا خطط لفترة تداخل قصيرة.

هل يعمل Account Kit على أي سلسلة متوافقة مع EVM؟ يدعم Account Kit شبكات Ethereum و Optimism و Arbitrum و Base و Polygon وشبكات الاختبار الخاصة بها. سياسات رعاية Gas Manager خاصة بكل سلسلة، لذا قم بإعدادها لكل شبكة.