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

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

جرّب Apidog اليوم

هذا الدليل عملي: ستتعلم اكتشاف المزود، طلب الحسابات، قراءة السلسلة، التوقيع باستخدام 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، وأضف شبكات جديدة بـ wallet_addEthereumChain.
• استخدم مكتبات مثل ethers.js v6 أو viem أو wagmi كطبقات عليا.
• اعتمد على Apidog لاختبار RPC، ومحاكاة المعاملات، وتصحيح التواقيع قبل الإطلاق.

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

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

خارج المتصفح، استخدم SDK ميتا ماسك للحصول على نفس السطح البرمجي في React Native، Node.js، Electron، وحتى السكريبتات الخلفية. SDK تدير الروابط العميقة (deep linking) وتفاعل رموز QR لتوقيع المعاملات من أجهزة مختلفة.

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

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

لا حاجة لمفاتيح API. المصادقة تتم بموافقة المستخدم على كل إجراء. تحتاج فقط لاكتشاف المزود والاستماع للتغييرات.

اكتشف المزود عبر @metamask/detect-provider أو مباشرة:

// اكتشاف المزود
import detectEthereumProvider from '@metamask/detect-provider';

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

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

اربط مستمعي الأحداث فورًا:

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 })

فيما يلي أهم الاستدعاءات العملية:

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

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

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

console.log(account, chainId); // مثال: '0x...' و '0x1'

للاستدعاءات للقراءة فقط، استخدم RPC عام مثل Infura أو Alchemy. راجع دليل Alchemy API.

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

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

توقيع بيانات منظمة (EIP-712)

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)],
});

إرسال معاملة

const txHash = await window.ethereum.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0xRecipientAddressHere', // ضع عنوان المستلم هنا
    value: '0x38d7ea4c68000', // 0.001 ETH بالـ wei (hex)
  }],
});

تبديل/إضافة سلسلة

// التبديل إلى Polygon – chainId: 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 ميتا ماسك في 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 API.

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

أكثر رموز الخطأ شيوعًا:

• 4001: المستخدم رفض الطلب. لا تعاود المحاولة تلقائيًا.
• 4100: غير مصرح به. الحساب غير متصل.
• 4200: طريقة غير مدعومة. تحقق أن المحفظة ميتا ماسك.
• 4902: السلسلة غير مضافة. استخدم wallet_addEthereumChain.
• -32002: طلب معلق فعليًا. قم بعمل debounce للأزرار.

المزود نفسه لا يفرض حدًا للمعدل، لكن مزودات RPC تفعل. للتعامل مع العملات الورقية والتحويلات، ستحتاج إلى واجهة API للتحويلات المالية.

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

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

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

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

• استورد مواصفات Ethereum JSON-RPC.
• اضبط عنوان عقدتك كمتغير بيئة.
• استفد من محاكاة الاستجابات لاختبار الواجهة الأمامية بدون عقد ذكي جاهز.
• شغّل الاختبارات في CI وفشّل البناء في حال تغيّر الاستجابة.

لشرح أفضل حول اختبار واجهات التطبيقات بدون Postman، راجع دليلنا: اختبار API بدون Postman في 2026.

حمل Apidog للبدء.

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

هل تعمل MetaMask API على الجوال؟

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

ما الفرق بين eth_sign وpersonal_sign وeth_signTypedData_v4?

eth_sign يوقع البايتات الخام (غير آمن). personal_sign يضيف بادئة للرسائل. eth_signTypedData_v4 يوقع بيانات EIP-712 المنظمة ويعرضها للمستخدم. استخدم الأخيرين، وتجنب eth_sign.

هل أحتاج لمفتاح API منفصل من ميتا ماسك؟

لا. المزود مجاني ولا يتطلب مفتاح. ستحتاج فقط مفتاحًا لمزود RPC مثل Infura أو Alchemy.

هل يمكنني استخدام ethers.js أو viem مع ميتا ماسك؟

نعم، كلاهما يدعم مزود window.ethereum مباشرة. استخدم BrowserProvider(window.ethereum) في ethers v6 أو createWalletClient({ transport: custom(window.ethereum) }) في viem.

ماذا لو كان لدى المستخدم عدة محافظ مثبتة؟

يدعم ميتا ماسك EIP-6963 لاكتشاف جميع المحافظ المثبتة. مكتبات مثل Wagmi وRainbowKit تدير ذلك تلقائيًا.

هل MetaMask Snaps جاهز للإنتاج؟

نعم، أصبح Snaps متاحًا للجميع في 2024. أبرز الاستخدامات: دعم سلاسل غير EVM، تنبيهات معاملات مخصصة، وتكامل محافظ الأجهزة.