Blog

Cách Sử Dụng MetaMask API: Kết Nối dApp với Ví Ethereum

Ashley Innocent

Ashley Innocent

23 tháng 4 2026

Cách Sử Dụng MetaMask API: Kết Nối dApp với Ví Ethereum

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

MetaMask là cổng mặc định để truy cập Ethereum dành cho hàng chục triệu người dùng, và nếu bạn điều hành một dApp, MetaMask API là thứ nằm giữa giao diện người dùng của bạn và các khóa ký của họ. "MetaMask API" là hai thứ trong một: nhà cung cấp window.ethereum được tiêm vào được định nghĩa bởi EIP-1193, và MetaMask SDK mở rộng bề mặt tương tự đó cho các ứng dụng di động, React Native và các backend Node.js. Nắm vững nhà cung cấp này, bạn đã học được 80% mọi tích hợp ví trên web.

Hướng dẫn này sẽ đi sâu vào việc phát hiện nhà cung cấp, yêu cầu tài khoản, đọc chuỗi hiện tại, ký tin nhắn bằng personal_sign và EIP-712, gửi giao dịch, thêm hoặc chuyển đổi chuỗi, và sử dụng MetaMask SDK khi bạn ở bên ngoài một tiện ích mở rộng trình duyệt. Bạn cũng sẽ thấy ethers.js v6 và viem phù hợp ở đâu với vai trò là các trình bao bọc cấp cao hơn, và nơi Apidog kết nối vào quy trình làm việc khi bạn muốn kiểm tra các lệnh gọi JSON-RPC cơ bản mà không cần viết mã frontend dùng một lần.

button

Nếu bạn đang xây dựng bất cứ thứ gì liên quan đến ví, hãy đánh dấu trang này cùng với hướng dẫn của chúng tôi về API ví tiền điện tử tốt nhất để có cái nhìn tổng quan hơn về bối cảnh nhà cung cấp.

TL;DR (Tóm tắt)

MetaMask API là gì?

MetaMask API là giao diện mà MetaMask hiển thị cho các trang web và ứng dụng để tương tác với Ethereum và các chuỗi tương thích EVM. Trong trình duyệt, tiện ích mở rộng chèn một đối tượng nhà cung cấp tại window.ethereum, và đối tượng đó tuân theo tiêu chuẩn EIP-1193. Bất kỳ dApp nào nhắm mục tiêu tiêu chuẩn đó đều hoạt động với MetaMask, Coinbase Wallet, Rabby, Frame và hàng chục dApp khác mà không cần thay đổi mã.

Bên ngoài trình duyệt, MetaMask SDK cung cấp cho bạn cấu trúc nhà cung cấp tương tự trong React Native, Node.js thuần túy, ứng dụng Electron dành cho máy tính để bàn và thậm chí cả tập lệnh phía máy chủ. SDK xử lý liên kết sâu (deep-linking) và quy trình mã QR cho phép ví MetaMask di động ký các giao dịch được yêu cầu bởi một quy trình máy tính để bàn hoặc backend. Về cơ bản, nó vẫn nói EIP-1193, vì vậy mã ứng dụng của bạn hầu như không thay đổi.

MetaMask cũng phát hành Snaps, một hệ thống plugin cho phép bên thứ ba mở rộng ví với các chuỗi mới, phương thức RPC tùy chỉnh và loại tài khoản. Snaps nằm ngoài phạm vi bài viết này, nhưng đáng để biết nếu bạn muốn hỗ trợ các chuỗi không phải EVM hoặc quy trình ký tùy chỉnh bên trong chính MetaMask.

Xác thực và thiết lập

Không có khóa API nào cho chính nhà cung cấp. Xác thực là người dùng chấp thuận từng yêu cầu trong giao diện ví của họ. Bạn cần hai thứ: một cách để phát hiện nhà cung cấp và một cách để lắng nghe các thay đổi.

Bắt đầu bằng việc phát hiện. Trình trợ giúp @metamask/detect-provider xử lý các trường hợp đặc biệt như nhiều ví được cài đặt, nhưng bạn cũng có thể kiểm tra trực tiếp.

// Phát hiện bằng Vanilla JS
import detectEthereumProvider from '@metamask/detect-provider';

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

if (!provider) {
  alert('Vui lòng cài đặt MetaMask');
} else {
  console.log('Đã phát hiện MetaMask');
}

Khi bạn có nhà cung cấp, hãy thiết lập các trình lắng nghe sự kiện trước khi bạn yêu cầu bất cứ điều gì. Bỏ sót sự kiện accountsChanged là lỗi tích hợp MetaMask phổ biến nhất.

window.ethereum.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    console.log('Người dùng đã ngắt kết nối');
  } else {
    console.log('Tài khoản đang hoạt động:', accounts[0]);
  }
});

window.ethereum.on('chainChanged', (chainId) => {
  // Thực hành tốt nhất: tải lại trang khi chuỗi thay đổi
  window.location.reload();
});

Đối với các ứng dụng React, wagmi xử lý tất cả những điều này cho bạn và tự động nhận diện MetaMask thông qua trình kết nối được tiêm vào của nó.

Các điểm cuối cốt lõi

Tất cả các lệnh gọi nhà cung cấp đều đi qua window.ethereum.request({ method, params }). Tên phương thức là một chuỗi JSON-RPC, và params là một mảng hoặc đối tượng tùy thuộc vào phương thức. Dưới đây là các lệnh gọi bao gồm 95% các tích hợp dApp.

Yêu cầu tài khoản và đọc chuỗi

// Nhắc người dùng kết nối
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// Đọc chuỗi hiện tại
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

console.log(account, chainId); // '0x...' '0x1' (Mạng chính Ethereum)

Lệnh gọi JSON-RPC thô tương đương, mà bạn có thể thực hiện tại bất kỳ nút Ethereum nào, trông như thế này với 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}'

Đối với các lệnh gọi chỉ đọc, bạn hoàn toàn không cần MetaMask; các nhà cung cấp nút như Alchemy hoặc Infura phục vụ cùng một RPC. Xem hướng dẫn Alchemy API của chúng tôi để có cái nhìn đầy đủ về các nút Ethereum được lưu trữ.

Ký một tin nhắn đơn giản

personal_sign là chữ ký cổ điển, dễ đọc. Nó thêm tiền tố vào tin nhắn để người dùng không bị lừa ký các byte giao dịch tùy ý.

const message = 'Đăng nhập vào Apidog vào lúc ' + new Date().toISOString();
const signature = await window.ethereum.request({
  method: 'personal_sign',
  params: [message, account],
});

Ký dữ liệu có cấu trúc với EIP-712

Đối với bất kỳ điều gì phức tạp, như giấy phép hoặc thử thách đăng nhập, hãy sử dụng eth_signTypedData_v4. MetaMask hiển thị các trường một cách rõ ràng trong cửa sổ bật lên xác nhận, điều này vừa bảo vệ người dùng vừa xây dựng lòng tin.

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

Gửi giao dịch

Các giao dịch sử dụng eth_sendTransaction. MetaMask tự động xử lý ước tính phí gas và quản lý nonce.

const txHash = await window.ethereum.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0xRecipientAddressHere',
    value: '0x38d7ea4c68000', // 0.001 ETH tính bằng wei, hệ thập lục phân
  }],
});

Chuyển đổi hoặc thêm một chuỗi

EIP-3326 và EIP-3085 bao gồm việc chuyển đổi sang một chuỗi đã biết và thêm một chuỗi mới.

// Chuyển sang Polygon (chainId 137 = 0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // Chuỗi chưa được thêm
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [{
        chainId: '0x89',
        chainName: 'Polygon',
        rpcUrls: ['https://polygon-rpc.com'],
        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
      }],
    });
  }
}

Sử dụng React với MetaMask SDK

SDK cũng hoạt động tốt trong React thông thường khi bạn muốn một đường dẫn tích hợp duy nhất bao gồm tiện ích mở rộng máy tính để bàn, liên kết sâu di động và trình duyệt trong ứng dụng.

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

function Connect() {
  const { sdk, connected, account } = useSDK();
  return (
    <button onClick={() => sdk?.connect()}>
      {connected ? account : 'Kết nối MetaMask'}
    </button>
  );
}

export default function App() {
  return (
    <MetaMaskProvider sdkOptions={{ dappMetadata: { name: 'dApp của tôi' } }}>
      <Connect />
    </MetaMaskProvider>
  );
}

Đối với các ứng dụng sản xuất, hãy gói nhà cung cấp thô trong ethers.js v6 hoặc viem. Chúng cung cấp cho bạn các hợp đồng được định kiểu, bộ giải mã ABI và thông báo lỗi tốt hơn trong khi vẫn giao tiếp với cùng một MetaMask API bên dưới. Nếu bạn cũng cần đăng nhập bằng email hoặc mạng xã hội làm phương án dự phòng, hãy kết hợp MetaMask với ví nhúng thông qua hướng dẫn Privy API của chúng tôi.

Các lỗi phổ biến và giới hạn tỷ lệ

MetaMask trả về các mã lỗi JSON-RPC tiêu chuẩn. Những lỗi bạn sẽ gặp thường xuyên nhất:

Bản thân nhà cung cấp không có giới hạn tỷ lệ, nhưng RPC cơ bản thì có. Nếu bạn đang ủy quyền đọc qua Infura hoặc Alchemy, bạn bị ràng buộc bởi cấp độ của họ. Đối với các luồng tiền pháp định như chuyển đổi ETH sang USD, hầu hết các nhóm kết hợp tích hợp này với API nạp và rút tiền pháp định để người dùng có thể nạp tiền mà không cần rời khỏi dApp.

Giá của MetaMask API

Tiện ích mở rộng MetaMask và SDK đều miễn phí. Không có phí cho mỗi kết nối, mỗi chữ ký hoặc mỗi giao dịch. MetaMask kiếm doanh thu thông qua phí hoán đổi khi người dùng giao dịch trong ví và thông qua MetaMask Card, chứ không phải từ các nhà phát triển dApp.

Chi phí bạn sẽ trả đến từ điểm cuối RPC mà dApp của bạn truy cập để đọc. Một gói miễn phí của Alchemy hoặc Infura đủ cho hầu hết các ứng dụng nhỏ; các dApp sản xuất thường có chi phí từ 49 đến 299 USD mỗi tháng cho thông lượng chuyên dụng.

Kiểm tra MetaMask API với Apidog

Ký kết dựa trên trình duyệt rất khó gỡ lỗi vì luồng yêu cầu trải rộng trên một tiện ích mở rộng, một trang và đôi khi là một liên kết sâu trên di động. Đó là nơi Apidog khẳng định vị trí của mình trong bộ công cụ phát triển ví. Bạn có thể truy cập điểm cuối JSON-RPC thô mà dApp của bạn sử dụng, xác nhận rằng eth_chainId và eth_getBalance trả về những gì bạn mong đợi, và lưu toàn bộ luồng đó dưới dạng một bộ kiểm thử.

Nhập đặc tả Ethereum JSON-RPC, đặt URL nút của bạn làm biến môi trường, và bạn có một bộ sưu tập có thể tái sử dụng cho mọi chuỗi EVM. Apidog cũng mô phỏng các phản hồi, để các nhà phát triển frontend của bạn có thể xây dựng dựa trên một eth_sendTransaction giả trong khi hợp đồng thông minh vẫn đang được kiểm toán. Đối với CI, bạn có thể chạy cùng bộ sưu tập từ dòng lệnh và làm cho bản dựng thất bại nếu hình dạng phản hồi thay đổi. Nếu bạn đã phải vật lộn với các bộ sưu tập Postman không bao giờ đồng bộ hóa giữa các nhóm, hướng dẫn của chúng tôi về kiểm thử API mà không cần Postman vào năm 2026 giải thích tại sao Apidog xử lý việc kiểm thử dApp đa giao thức tốt hơn.

Tải xuống Apidog để bắt đầu.

Câu hỏi thường gặp

MetaMask API có hoạt động trên thiết bị di động không?Có. Sử dụng MetaMask SDK, liên kết sâu đến ứng dụng di động để ký. Bề mặt nhà cung cấp giống hệt tiện ích mở rộng trình duyệt, vì vậy mã của bạn vẫn giữ nguyên. Để so sánh sâu hơn với các SDK ví di động khác, hãy xem bài tổng hợp về API ví tiền điện tử tốt nhất của chúng tôi.

Sự khác biệt giữa eth_sign, personal_sign và eth_signTypedData_v4 là gì?eth_sign ký các byte thô và nguy hiểm; MetaMask cảnh báo người dùng rất tích cực. personal_sign thêm tiền tố vào một tin nhắn dễ đọc. eth_signTypedData_v4 ký dữ liệu EIP-712 có cấu trúc và hiển thị các trường rõ ràng trong giao diện người dùng MetaMask. Hãy sử dụng hai cái cuối cùng; tránh eth_sign.

Tôi có cần một khóa API riêng từ MetaMask không?Không. Nhà cung cấp miễn phí và không cần khóa. Bạn cần một nhà cung cấp RPC như Alchemy hoặc Infura để đọc dữ liệu bên ngoài ví, những cái này có khóa riêng của chúng.

Tôi có thể sử dụng ethers.js hoặc viem với MetaMask không?Có, cả hai đều bao bọc nhà cung cấp window.ethereum. Ethers v6 hiển thị BrowserProvider(window.ethereum), và viem có createWalletClient({ transport: custom(window.ethereum) }). Hầu hết các dApp sản xuất đều sử dụng một trong hai.

Điều gì xảy ra nếu người dùng cài đặt nhiều ví?MetaMask triển khai EIP-6963, vì vậy các dApp có thể phát hiện tất cả các ví đã cài đặt thay vì tranh giành window.ethereum. Wagmi và RainbowKit xử lý điều này tự động.

MetaMask Snaps đã sẵn sàng cho sản xuất chưa?Có, Snaps đã được phát hành rộng rãi vào năm 2024. Hầu hết các trường hợp sử dụng trong sản xuất là để hỗ trợ chuỗi không phải EVM, thông tin chi tiết giao dịch tùy chỉnh và tích hợp ví phần cứng.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống