كيفية استخدام واجهة برمجة تطبيقات MetaMask: ربط تطبيقك اللامركزي بمحافظ Ethereum

ميتا ماسك هو نقطة الوصول الافتراضية إلى الإيثيريوم لعشرات الملايين من المستخدمين، وإذا كنت تدير تطبيقًا لامركزيًا (dApp)، فإن واجهة برمجة تطبيقات ميتا ماسك (MetaMask API) هي التي تتوسط بين واجهة المستخدم الخاصة بك ومفاتيح التوقيع الخاصة بهم. "واجهة برمجة تطبيقات ميتا ماسك" هي في الأساس شيئان متكاملان: مزود window.ethereum المحقون والمحدد بواسطة EIP-1193، وحزمة تطوير البرمجيات (SDK) الخاصة بميتا ماسك التي توسع نفس السطح ليشمل تطبيقات الجوال، وReact Native، والخلفيات التي تعمل بـ Node.js. تعلم المزود، وستكون قد تعلمت 80% من كل تكامل للمحافظ على الويب.

يرشدك هذا الدليل خلال اكتشاف المزود، وطلب الحسابات، وقراءة السلسلة الحالية، وتوقيع الرسائل باستخدام personal_sign وEIP-712، وإرسال المعاملات، وإضافة أو تبديل السلاسل، واستخدام حزمة تطوير البرمجيات (SDK) الخاصة بميتا ماسك عندما تكون خارج إضافة المتصفح. سترى أيضًا أين تتناسب مكتبتا ethers.js v6 وviem كأغلفة عالية المستوى، وأين يندمج Apidog في سير العمل عندما ترغب في اختبار استدعاءات JSON-RPC الأساسية دون كتابة تعليمات برمجية واجهة أمامية مؤقتة.

زر

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

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

واجهة برمجة تطبيقات ميتا ماسك هي مزود EIP-1193 المعروض في window.ethereum في المتصفحات، بالإضافة إلى حزمة تطوير البرمجيات (SDK) الخاصة بميتا ماسك للجوال وNode.
ابدأ باستخدام eth_requestAccounts لمطالبة المستخدم بالاتصال، ثم استمع إلى حدثي accountsChanged وchainChanged.
وقّع الرسائل باستخدام personal_sign، ووقّع البيانات المنظمة باستخدام eth_signTypedData_v4 (EIP-712).
بدّل الشبكات باستخدام wallet_switchEthereumChain (EIP-3326) وأضف شبكات جديدة باستخدام wallet_addEthereumChain (EIP-3085).
المكتبات عالية المستوى مثل ethers.js v6 وviem وwagmi تغلف المزود الخام؛ بينما تعمل Snaps على توسيع ميتا ماسك نفسه.
استخدم Apidog لاختبار نقاط نهاية JSON-RPC، ومحاكاة استجابات المعاملات، وتصحيح أخطاء التوقيعات قبل النشر.

ما هي واجهة برمجة تطبيقات ميتا ماسك (MetaMask API)؟

واجهة برمجة تطبيقات ميتا ماسك هي الواجهة التي يعرضها ميتا ماسك لصفحات الويب والتطبيقات للتفاعل مع الإيثيريوم والسلاسل المتوافقة مع EVM. في المتصفح، تقوم الإضافة بحقن كائن مزود في window.ethereum، وهذا الكائن يتبع معيار EIP-1193. أي تطبيق لامركزي (dApp) يستهدف هذا المعيار يعمل مع ميتا ماسك، ومحفظة Coinbase، ورابي، وفريم، وعشرات غيرها دون أي تغييرات في التعليمات البرمجية.

خارج المتصفح، تمنحك حزمة تطوير البرمجيات (SDK) الخاصة بميتا ماسك نفس شكل المزود في React Native، وNode.js الخام، وتطبيقات سطح المكتب Electron، وحتى السكريبتات من جانب الخادم. تتولى حزمة SDK التعامل مع الروابط العميقة (deep-linking) وتفاعلات رموز QR التي تسمح لمحفظة ميتا ماسك على الجوال بتوقيع المعاملات المطلوبة من قبل عملية على سطح المكتب أو الخلفية. في الأساس، لا تزال تتحدث EIP-1193، لذا فإن تعليمات تطبيقك البرمجية تتغير بالكاد.

يقدم ميتا ماسك أيضًا Snaps، وهو نظام إضافات يسمح لأطراف ثالثة بتوسيع المحفظة بسلاسل جديدة، وطرق RPC مخصصة، وأنواع حسابات. Snaps خارج نطاق هذا الدليل، لكنها تستحق المعرفة إذا كنت ترغب في دعم سلاسل غير متوافقة مع EVM أو تدفقات توقيع مخصصة داخل ميتا ماسك نفسه.

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

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

ابدأ بالاكتشاف. يتعامل المساعد @metamask/detect-provider مع الحالات الخاصة مثل تثبيت عدة محافظ، ولكن يمكنك أيضًا التحقق مباشرةً.

// اكتشاف JavaScript عادي
import detectEthereumProvider from '@metamask/detect-provider';

const provider = await detectEthereumProvider({ mustBeMetaMask: true });

if (!provider) {
  alert('الرجاء تثبيت ميتا ماسك');
} else {
  console.log('تم اكتشاف ميتا ماسك');
}

بمجرد حصولك على المزود، قم بربط مستمعي الأحداث قبل أن تطلب أي شيء. فقدان حدث accountsChanged هو أكثر أخطاء تكامل ميتا ماسك شيوعًا.

window.ethereum.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    console.log('تم قطع اتصال المستخدم');
  } else {
    console.log('الحساب النشط:', accounts[0]);
  }
});

window.ethereum.on('chainChanged', (chainId) => {
  // أفضل ممارسة: إعادة تحميل الصفحة عند تغيير السلسلة
  window.location.reload();
});

بالنسبة لتطبيقات React، تتولى wagmi كل هذا نيابة عنك وتكتشف ميتا ماسك تلقائيًا عبر موصلها المحقون.

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

تتم جميع استدعاءات المزود عبر window.ethereum.request({ method, params }). اسم الطريقة هو سلسلة JSON-RPC، وparams هي مصفوفة أو كائن حسب الطريقة. فيما يلي الاستدعاءات التي تغطي 95% من عمليات تكامل التطبيقات اللامركزية (dApp).

طلب الحسابات وقراءة السلسلة

// اطلب من المستخدم الاتصال
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// قراءة السلسلة الحالية
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

console.log(account, chainId); // '0x...' '0x1' (شبكة إيثيريوم الرئيسية)

استدعاء JSON-RPC الخام المكافئ، والذي يمكنك إطلاقه على أي عقدة إيثيريوم، يبدو كالتالي باستخدام curl.

curl https://mainnet.infura.io/v3/YOUR_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

بالنسبة للاستدعاءات للقراءة فقط، لا تحتاج إلى ميتا ماسك على الإطلاق؛ فمزودو العقد مثل Alchemy أو Infura يقدمون نفس RPC. راجع دليل واجهة برمجة تطبيقات Alchemy الخاص بنا للحصول على الصورة الكاملة حول عقد الإيثيريوم المستضافة.

توقيع رسالة بسيطة

personal_sign هو التوقيع الكلاسيكي المقروء بشريًا. يقوم بإضافة بادئة إلى الرسالة حتى لا يتم خداع المستخدمين لتوقيع بايتات معاملة عشوائية.

const message = 'Sign in to Apidog at ' + new Date().toISOString();
const signature = await window.ethereum.request({
  method: 'personal_sign',
  params: [message, account],
});

توقيع البيانات المنظمة باستخدام EIP-712

لأي شيء معقد، مثل إذن (permit) أو تحدي تسجيل دخول، استخدم eth_signTypedData_v4. يعرض ميتا ماسك الحقول بوضوح في النافذة المنبثقة للتأكيد، مما يحمي المستخدمين ويبني الثقة.

const typedData = {
  domain: { name: 'Apidog Demo', version: '1', chainId: 1 },
  types: {
    EIP712Domain: [
      { name: 'name', type: 'string' },
      { name: 'version', type: 'string' },
      { name: 'chainId', type: 'uint256' },
    ],
    Login: [
      { name: 'wallet', type: 'address' },
      { name: 'nonce', type: 'uint256' },
    ],
  },
  primaryType: 'Login',
  message: { wallet: account, nonce: 42 },
};

const sig = await window.ethereum.request({
  method: 'eth_signTypedData_v4',
  params: [account, JSON.stringify(typedData)],
});

إرسال معاملة

تستخدم المعاملات eth_sendTransaction. يتعامل ميتا ماسك مع تقدير الغاز وإدارة nonce تلقائيًا.

const txHash = await window.ethereum.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0xRecipientAddressHere', // عنوان المستلم هنا
    value: '0x38d7ea4c68000', // 0.001 إيثيريوم بوحدة wei، سداسي عشري
  }],
});

تبديل أو إضافة سلسلة

تغطي EIP-3326 وEIP-3085 التبديل إلى سلسلة معروفة وإضافة سلسلة جديدة.

// التبديل إلى Polygon (معرف السلسلة 137 = 0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // لم تتم إضافة السلسلة بعد
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [{
        chainId: '0x89',
        chainName: 'Polygon',
        rpcUrls: ['https://polygon-rpc.com'],
        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
      }],
    });
  }
}

التفاعل مع حزمة تطوير البرمجيات (SDK) الخاصة بميتا ماسك

تعمل حزمة تطوير البرمجيات (SDK) بشكل جيد أيضًا في React العادي عندما تريد مسار تكامل واحد يغطي إضافة سطح المكتب، والروابط العميقة على الجوال، والمتصفح داخل التطبيق.

import { MetaMaskProvider, useSDK } from '@metamask/sdk-react';

function Connect() {
  const { sdk, connected, account } = useSDK();
  return (
    <button onClick={() => sdk?.connect()}>
      {connected ? account : 'اتصل بميتا ماسك'}
    </button>
  );
}

export default function App() {
  return (
    <MetaMaskProvider sdkOptions={{ dappMetadata: { name: 'تطبيقي اللامركزي' } }}>
      <Connect />
    </MetaMaskProvider>
  );
}

بالنسبة لتطبيقات الإنتاج، قم بتغليف المزود الخام في ethers.js v6 أو viem. فهما يوفران لك عقودًا مكتوبة (typed contracts)، ومحللات ABI، ورسائل خطأ أفضل بينما لا يزالان يتحدثان إلى نفس واجهة برمجة تطبيقات ميتا ماسك الأساسية. إذا كنت تحتاج أيضًا إلى تسجيل الدخول عبر البريد الإلكتروني أو الشبكات الاجتماعية كخيار احتياطي، فقم بإقران ميتا ماسك بمحفظة مدمجة عبر دليل واجهة برمجة تطبيقات Privy الخاص بنا.

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

يعيد ميتا ماسك رموز خطأ JSON-RPC القياسية. الأكثر شيوعًا التي ستصادفها:

4001: رفض المستخدم الطلب. اعرض إشعارًا وديًا بـ "تم إلغاء الاتصال" ولا تحاول إعادة المحاولة تلقائيًا.
4100: غير مصرح به. الحساب غير متصل؛ استدعِ eth_requestAccounts أولاً.
4200: طريقة غير مدعومة. نادرًا ما تحدث، ولكن تأكد من أن المحفظة هي ميتا ماسك قبل استدعاء الطرق الخاصة بالمورد.
4902: لم تتم إضافة السلسلة. تابع باستخدام wallet_addEthereumChain.
-32002: الطلب معلق بالفعل. قد ينقر المستخدمون على الزر مرتين؛ قم بإلغاء التكرار من جانبك (debounce).

لا يمتلك المزود نفسه حدًا للمعدل (rate limit)، ولكن RPC الأساسي يمتلك ذلك. إذا كنت تقوم بالوكالة في عمليات القراءة عبر Infura أو Alchemy، فأنت مقيد بالطبقة الخاصة بهم. لتدفقات العملات الورقية مثل تحويل الإيثيريوم إلى الدولار الأمريكي، تقوم معظم الفرق بإقران هذا التكامل بواجهة API لتشغيل وإيقاف العملات الورقية (fiat on-ramp and off-ramp API) حتى يتمكن المستخدمون من شحن الرصيد دون مغادرة التطبيق اللامركزي.

تسعير واجهة برمجة تطبيقات ميتا ماسك

إضافة ميتا ماسك وحزمة تطوير البرمجيات (SDK) مجانيتان. لا توجد رسوم لكل اتصال، أو لكل توقيع، أو لكل معاملة. يكسب ميتا ماسك الإيرادات من خلال رسوم التبادل عندما يتداول المستخدمون داخل المحفظة وعبر بطاقة ميتا ماسك، وليس من مطوري التطبيقات اللامركزية.

تأتي التكاليف التي ستدفعها من نقطة نهاية RPC التي يستخدمها تطبيقك اللامركزي لعمليات القراءة. تتعامل طبقة Alchemy أو Infura المجانية مع معظم التطبيقات الصغيرة؛ بينما عادةً ما تتراوح تكلفة التطبيقات اللامركزية في الإنتاج بين 49 دولارًا و299 دولارًا شهريًا للإنتاجية المخصصة.

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

يصعب تصحيح أخطاء التوقيع المستند إلى المتصفح لأن تدفق الطلب يمتد عبر إضافة، وصفحة، وأحيانًا رابط عميق على الجوال. وهنا يكتسب Apidog مكانه في مجموعة أدوات مطور المحفظة. يمكنك استهداف نقطة نهاية JSON-RPC الخام التي يستخدمها تطبيقك اللامركزي، والتأكد من أن eth_chainId وeth_getBalance تعيدان ما تتوقعه، وحفظ التدفق بأكمله كمجموعة اختبار.

قم باستيراد مواصفات Ethereum JSON-RPC، واضبط عنوان URL لعقدتك كمتغير بيئة، وسيكون لديك مجموعة قابلة لإعادة الاستخدام لكل سلسلة EVM. يقوم Apidog أيضًا بمحاكاة الاستجابات، بحيث يمكن لمطوري الواجهة الأمامية البناء مقابل eth_sendTransaction وهمي بينما لا يزال العقد الذكي قيد التدقيق. بالنسبة للتكامل المستمر (CI)، يمكنك تشغيل نفس المجموعة من سطر الأوامر وفشل البناء إذا تغير شكل الاستجابة. إذا كنت تكافح مع مجموعات Postman التي لا تتم مزامنتها أبدًا عبر الفريق، فإن دليلنا حول اختبار واجهة برمجة التطبيقات بدون Postman في عام 2026 يشرح لماذا يتعامل Apidog مع اختبار التطبيقات اللامركزية متعددة البروتوكولات بشكل أفضل.

حمل Apidog للبدء.

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

هل تعمل واجهة برمجة تطبيقات ميتا ماسك على الجوال؟
نعم. استخدم حزمة تطوير البرمجيات (SDK) الخاصة بميتا ماسك، والتي تقوم بالربط العميق (deep-links) بالتطبيق الجوال للتوقيع. سطح المزود مطابق لإضافة المتصفح، لذا يظل رمزك كما هو. لمقارنة أعمق مع حزم SDK الأخرى لمحافظ الجوال، راجع ملخصنا لأفضل واجهة برمجة تطبيقات لمحفظة العملات المشفرة.

ما الفرق بين eth_sign وpersonal_sign وeth_signTypedData_v4؟
يوقع eth_sign البايتات الخام وهو خطير؛ يحذر ميتا ماسك المستخدمين بقوة منه. personal_sign يضيف بادئة إلى رسالة قابلة للقراءة البشرية. eth_signTypedData_v4 يوقع بيانات EIP-712 المنظمة ويعرض الحقول بوضوح في واجهة مستخدم ميتا ماسك. استخدم الأخيرين؛ تجنب eth_sign.

هل أحتاج إلى مفتاح API منفصل من ميتا ماسك؟
لا. المزود مجاني وبدون مفتاح. تحتاج إلى مزود RPC مثل Alchemy أو Infura للقراءة خارج المحفظة، والذين لديهم مفاتيح خاصة بهم.

هل يمكنني استخدام ethers.js أو viem مع ميتا ماسك؟
نعم، كلاهما يغلف مزود window.ethereum. Ethers v6 يعرض BrowserProvider(window.ethereum)، وviem لديه createWalletClient({ transport: custom(window.ethereum) }). تستخدم معظم التطبيقات اللامركزية في الإنتاج أحد هذين الخيارين.

ماذا يحدث إذا كان لدى المستخدم عدة محافظ مثبتة؟
يطبق ميتا ماسك EIP-6963، بحيث يمكن للتطبيقات اللامركزية اكتشاف جميع المحافظ المثبتة بدلاً من التنافس على window.ethereum. تتولى Wagmi وRainbowKit هذا الأمر تلقائيًا.

هل MetaMask Snaps جاهز للإنتاج؟
نعم، أصبح Snaps متاحًا بشكل عام في عام 2024. معظم الاستخدام في الإنتاج هو لدعم سلاسل غير EVM، وتنبيهات المعاملات المخصصة، وتكامل محافظ الأجهزة (hardware wallets).