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.
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à nhà cung cấp EIP-1193 được hiển thị tại
window.ethereumtrong trình duyệt, cộng với MetaMask SDK cho di động và Node. - Bắt đầu với
eth_requestAccountsđể nhắc người dùng kết nối, sau đó lắng nghe các sự kiệnaccountsChangedvàchainChanged. - Ký tin nhắn bằng
personal_sign, và ký dữ liệu có cấu trúc bằngeth_signTypedData_v4(EIP-712). - Chuyển đổi mạng bằng
wallet_switchEthereumChain(EIP-3326) và thêm mạng mới bằngwallet_addEthereumChain(EIP-3085). - Các thư viện cấp cao hơn như ethers.js v6, viem và wagmi bao bọc nhà cung cấp thô; Snaps mở rộng chính MetaMask.
- Sử dụng Apidog để kiểm tra các điểm cuối JSON-RPC, mô phỏng phản hồi giao dịch và gỡ lỗi chữ ký trước khi triển khai.
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:
4001: Người dùng đã từ chối yêu cầu. Hiển thị thông báo "kết nối đã bị hủy" thân thiện và không tự động thử lại.4100: Không được ủy quyền. Tài khoản chưa được kết nối; hãy gọieth_requestAccountstrước.4200: Phương thức không được hỗ trợ. Hiếm gặp, nhưng hãy xác nhận ví là MetaMask trước khi gọi các phương thức dành riêng cho nhà cung cấp.4902: Chuỗi chưa được thêm. Tiếp theo là gọiwallet_addEthereumChain.-32002: Yêu cầu đang chờ xử lý. Người dùng đôi khi nhấp vào nút hai lần; hãy xử lý độ trễ (debounce) ở phía bạn.
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.