diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 72fa40a9563..739a89cb28f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -71,9 +71,9 @@ To contribute changes:
> **Notes:**
>
- > - All documentation content is located in the `wallet`, `snaps`, `services`, and
+ > - All documentation content is located in the `wallet`, `sdk`, `snaps`, `services`, and
> `developer-tools` directories.
- > - If you add a new documentation page, edit `wallet-sidebar.js`, `snaps-sidebar.js`,
+ > - If you add a new documentation page, edit `wallet-sidebar.js`, `sdk-sidebar.js`, `snaps-sidebar.js`,
> `services-sidebar.js`, or `dashboard-sidebar.js` to add the page to the
> [sidebar](https://docs-template.consensys.io/create/configure-docusaurus#sidebar).
> - If you delete, rename, or move a documentation file, add a
@@ -120,7 +120,7 @@ Refer to the [Consensys documentation style guide](https://docs-template.consens
## Add images
-All images are located in the `wallet/assets`, `snaps/assets`, `services/images`, and
+All images are located in the `wallet/assets`, `sdk/_assets`, `snaps/assets`, `services/images`, and
`developer-tools/images` directories.
When adding a new image, such as a screenshot or diagram, make sure the image has a white or
`#1b1b1d` color background in order for it to be compatible with the site's light and dark modes.
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 6e49746d33f..30edcc5ad11 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -151,6 +151,17 @@ const config = {
}
},
],
+ [
+ "@docusaurus/plugin-content-docs",
+ {
+ id: "sdk",
+ path: "sdk",
+ routeBasePath: "sdk",
+ editUrl: "https://github.com/MetaMask/metamask-docs/edit/main/",
+ sidebarPath: require.resolve("./sdk-sidebar.js"),
+ breadcrumbs: false,
+ },
+ ],
"./src/plugins/plugin-json-rpc.ts",
isProd
? [
@@ -178,9 +189,13 @@ const config = {
width: 150,
},
items: [
+ {
+ to: "sdk",
+ label: "SDK",
+ },
{
to: "wallet",
- label: "Wallet",
+ label: "Wallet API",
},
{
to: "snaps",
@@ -248,6 +263,10 @@ const config = {
label: "Wallet",
to: "/wallet",
},
+ {
+ label: "SDK",
+ to: "/sdk",
+ },
{
label: "Snaps",
to: "/snaps",
diff --git a/sdk-sidebar.js b/sdk-sidebar.js
new file mode 100644
index 00000000000..724e7a93ebe
--- /dev/null
+++ b/sdk-sidebar.js
@@ -0,0 +1,68 @@
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebar = {
+ sdkSidebar: [
+ {
+ type: 'category',
+ label: 'Introduction',
+ collapsible: false,
+ collapsed: false,
+ items: [
+ 'introduction/welcome',
+ 'introduction/supported-platforms',
+ 'introduction/supported-networks',
+ 'introduction/llm-prompt',
+ {
+ type: 'link',
+ label: 'Try Demo App',
+ href: 'https://metamask-sdk-examples-relink.vercel.app/',
+ },
+ ],
+ },
+ {
+ type: 'category',
+ label: 'Quick Start',
+ collapsible: false,
+ collapsed: false,
+ items: [
+ 'quick-start/javascript-+-wagmi',
+ 'quick-start/javascript',
+ 'quick-start/react-native',
+ ],
+ },
+ {
+ type: 'category',
+ label: 'Guides',
+ collapsible: false,
+ collapsed: false,
+ items: [
+ 'guides/user-authentication',
+ 'guides/network-management',
+ 'guides/transaction-handling',
+ 'guides/interact-with-contracts',
+ {
+ type: 'category',
+ label: 'Advanced',
+ collapsible: true,
+ collapsed: true,
+ items: [
+ 'guides/advanced/connect-and-sign',
+ 'guides/advanced/batch-requests',
+ ],
+ },
+ ],
+ },
+ {
+ type: 'category',
+ label: 'API Reference',
+ collapsible: false,
+ collapsed: false,
+ items: [
+ 'api-reference/sdk-api'
+ ],
+ }
+ ],
+};
+
+module.exports = sidebar;
diff --git a/sdk/_assets/connect.gif b/sdk/_assets/connect.gif
new file mode 100644
index 00000000000..d2f794ce8b6
Binary files /dev/null and b/sdk/_assets/connect.gif differ
diff --git a/sdk/_assets/network.gif b/sdk/_assets/network.gif
new file mode 100644
index 00000000000..ed597169380
Binary files /dev/null and b/sdk/_assets/network.gif differ
diff --git a/sdk/_assets/quickstart.jpg b/sdk/_assets/quickstart.jpg
new file mode 100644
index 00000000000..6f023ecb93e
Binary files /dev/null and b/sdk/_assets/quickstart.jpg differ
diff --git a/sdk/api-reference/sdk-api.md b/sdk/api-reference/sdk-api.md
new file mode 100644
index 00000000000..d515c4bb6f4
--- /dev/null
+++ b/sdk/api-reference/sdk-api.md
@@ -0,0 +1,313 @@
+---
+description: SDK options
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# SDK options
+
+The [JavaScript version of MetaMask SDK](../connect/metamask-sdk/javascript/index.md) takes the
+following options.
+
+### `checkInstallationImmediately`
+
+
+
+
+```javascript
+checkInstallationImmediately:
+```
+
+
+
+
+```javascript
+checkInstallationImmediately: true
+```
+
+
+
+
+Enables or disables immediately checking if MetaMask is installed on the user's browser.
+If `true`, the SDK checks for installation upon page load and sends a connection request, prompting
+the user to install MetaMask if it's not already installed.
+If `false`, the SDK waits for the connect method to be called to check for installation.
+
+The default is `false`.
+
+### `checkInstallationOnAllCalls`
+
+
+
+
+```javascript
+checkInstallationOnAllCalls:
+```
+
+
+
+
+```javascript
+checkInstallationOnAllCalls: true
+```
+
+
+
+
+Enables or disables checking if MetaMask is installed on the user's browser before each RPC request.
+The default is `false`.
+
+### `communicationServerUrl`
+
+
+
+
+```javascript
+communicationServerUrl:
+```
+
+
+
+
+```javascript
+communicationServerUrl: "https://metamask-sdk-socket.metafi.codefi.network/"
+```
+
+
+
+
+The URL of the communication server to use.
+This option is mainly used for debugging and testing the SDK.
+
+### `dappMetadata`
+
+
+
+
+```javascript
+dappMetadata: {
+ name: ,
+ url: ,
+ iconUrl: ,
+}
+```
+
+
+
+
+```javascript
+dappMetadata: {
+ name: "My Dapp",
+ url: "https://mydapp.com",
+ iconUrl: "https://mydapp.com/icon.png",
+}
+```
+
+
+
+
+Metadata about the dapp using the SDK.
+The metadata options are:
+
+- `name` - Name of the dapp
+- `url` - URL of the dapp
+- `iconUrl` - URL of the dapp's icon
+
+:::tip important
+Setting `dappMetaData` creates a clear and trustworthy user experience when connecting your dapp to
+MetaMask Mobile.
+MetaMask Mobile displays this metadata in the connection modal to help users identify and verify the
+connection request.
+:::
+
+### `defaultReadOnlyChainId`
+
+
+
+
+```javascript
+defaultReadOnlyChainId:
+```
+
+
+
+
+```javascript
+defaultReadOnlyChainId: "0x1"
+```
+
+
+
+
+Enables sending [read-only RPC requests](../how-to/make-read-only-requests.md) to
+this chain ID before the user connects to MetaMask.
+The value is automatically updated to the chain ID used in MetaMask once connected.
+
+### `enableAnalytics`
+
+
+
+
+```javascript
+enableAnalytics:
+```
+
+
+
+
+```javascript
+enableAnalytics: true
+```
+
+
+
+
+Enables or disables sending anonymous analytics to MetaMask to help improve the SDK.
+The default is `true`.
+
+### `extensionOnly`
+
+
+
+
+```javascript
+extensionOnly:
+```
+
+
+
+
+```javascript
+extensionOnly: true
+```
+
+
+
+
+Enables or disables automatically using the MetaMask browser extension if it's detected.
+The default is `true`.
+
+### `infuraAPIKey`
+
+
+
+
+```javascript
+infuraAPIKey:
+```
+
+
+
+
+```javascript
+infuraAPIKey: process.env.INFURA_API_KEY
+```
+
+
+
+
+The [Infura API key](/developer-tools/dashboard/get-started/create-api) to
+use for RPC requests.
+Configure this option to [make read-only RPC requests from your dapp](../how-to/make-read-only-requests.md).
+
+:::caution important
+Use [Infura allowlists](https://docs.infura.io/networks/ethereum/how-to/secure-a-project/use-an-allowlist)
+to protect against other people submitting requests to your API key.
+You can restrict interactions to specific addresses, origins, user agents, and request methods.
+We recommend using all allowlist options to maximize the security of your API key and dapp.
+:::
+
+### `headless`
+
+
+
+
+```javascript
+headless:
+```
+
+
+
+
+```javascript
+headless: true
+```
+
+
+
+
+Enables or disables headless mode.
+Setting this to `true` allows you to [display custom modals](../how-to/display/custom-modals.md).
+The default is `false`.
+
+### `openDeeplink`
+
+
+
+
+```javascript
+openDeeplink:
+```
+
+
+
+
+```javascript
+openDeeplink: (link: string) => {
+ if (canOpenLink) {
+ Linking.openURL(link);
+ }
+}
+```
+
+
+
+
+A function that is called to open a deeplink to the MetaMask Mobile app.
+
+### `readonlyRPCMap`
+
+
+
+
+```javascript
+readonlyRPCMap:
+
+
+```javascript
+readonlyRPCMap: {
+ "0x539": "http://localhost:8545",
+}
+```
+
+
+
+
+A map of RPC URLs to use for [read-only RPC requests](../how-to/make-read-only-requests.md).
+
+### `shouldShimWeb3`
+
+
+
+
+```javascript
+shouldShimWeb3:
+```
+
+
+
+
+```javascript
+shouldShimWeb3: false
+```
+
+
+
+
+Enables or disables shimming the `window.web3` object with the Ethereum provider returned by the SDK
+(useful for compatibility with older browsers).
+The default is `true`.
diff --git a/sdk/guides/advanced/batch-requests.md b/sdk/guides/advanced/batch-requests.md
new file mode 100644
index 00000000000..312e31f7b38
--- /dev/null
+++ b/sdk/guides/advanced/batch-requests.md
@@ -0,0 +1,140 @@
+---
+description: Batch multiple JSON-RPC requests using MetaMask SDK.
+tags:
+ - JavaScript SDK
+---
+
+# Batch Requests
+
+You can batch multiple JSON-RPC requests using MetaMask SDK.
+
+:::info
+
+Check out the [JSON-RPC API](/wallet/reference/json-rpc-methods) reference for more information.
+
+:::
+
+The SDK's `metamask_batch` method enables you to batch multiple JSON-RPC requests in a single call,
+providing a streamlined approach for dapps to interact with EVM networks, and enabling complex
+sequences of actions.
+This method enhances performance, usability, and efficiency by reducing the number of network calls
+made to MetaMask.
+
+Use cases include:
+
+- **Batching multiple signatures** - Send multiple signing requests in one batch.
+
+- **Switching networks** - Switch the EVM network, perform an action such as sending a transaction,
+ and switch back, all in one batch.
+
+- **Mixed transactions and signatures** - Combine transaction sending and signing requests in one batch.
+
+`metamask_batch` opens up additional possibilities for sophisticated transaction flows in dapps,
+enhancing the user experience and operational efficiency.
+
+## Prerequisites
+
+Set up MetaMask SDK in your JavaScript dapp.
+
+## Use the `metamask_batch` method
+
+`metamask_batch` takes an array of JSON-RPC requests (`ChainRPC[]`) as its parameter.
+
+Each request in the batch is independent.
+The user receives a prompt for each action within the batch, allowing them to approve or reject
+individual requests.
+If any request is rejected, the entire batch fails and an error is returned, ensuring integrity in
+transactional operations.
+
+The method returns an array of results corresponding to each request.
+
+### React / Next.js / React Native example
+
+The following is an example of using `metamask_batch` to batch
+[`personal_sign`](/wallet/reference/json-rpc-methods/personal_sign) and
+[`eth_sendTransaction`](/wallet/reference/json-rpc-methods/eth_sendtransaction) in React, Next.js, or React Native/Expo:
+
+```javascript title="index.js"
+import { metamask_batch } from "metamask-sdk"
+
+function MyComponent() {
+ const handleBatchRequest = async () => {
+ const batchRequests = [
+ { method: "personal_sign", params: ["message", "address"] },
+ {
+ method: "eth_sendTransaction",
+ params: [
+ {
+ /* Transaction parameters */
+ },
+ ],
+ },
+ ]
+
+ try {
+ const results = await metamask_batch(batchRequests)
+ console.log(results) // Process results.
+ } catch (error) {
+ console.error("Batch request failed", error)
+ }
+ }
+
+ return
+}
+```
+
+### Vue.js example
+
+The following is an example of using `metamask_batch` to batch
+[`personal_sign`](/wallet/reference/json-rpc-methods/personal_sign) and
+[`eth_sendTransaction`](/wallet/reference/json-rpc-methods/eth_sendtransaction) in Vue.js:
+
+```javascript title="App.vue"
+
+```
+
+### Best practices
+
+Follow these guidelines when using `metamask_batch`:
+
+- **Ensure each request in the batch is properly formatted** according to the JSON-RPC specifications.
+
+- **Handle errors appropriately**, especially when a batch request is partially approved.
+
+- **Test batch operations** to ensure consistent behavior across different networks and accounts.
+
+- **Be aware of the dependencies between chained requests.**
+ Avoid creating a dependency where the outcome of one request directly influences the context or
+ validity of a subsequent request within the same batch.
+ For example, avoid chaining a [`wallet_switchEthereumChain`](/wallet/reference/json-rpc-methods/wallet_switchethereumchain)
+ request with [`eth_signTypedData_v4`](/wallet/reference/json-rpc-methods/eth_signtypeddata_v4), because
+ `eth_signTypedData_v4` relies on the current chain ID, which would be altered by `wallet_switchEthereumChain`.
+ This approach ensures that each request in the batch operates independently and maintains its
+ integrity, regardless of changes introduced by preceding requests in the batch.
diff --git a/sdk/guides/advanced/connect-and-sign.md b/sdk/guides/advanced/connect-and-sign.md
new file mode 100644
index 00000000000..f1b4d4d173a
--- /dev/null
+++ b/sdk/guides/advanced/connect-and-sign.md
@@ -0,0 +1,108 @@
+---
+description: Use MetaMask SDK to connect and sign in a single interaction.
+tags:
+ - JavaScript SDK
+ - iOS SDK
+---
+
+# Connect and Sign
+
+You can connect to MetaMask and sign data in a single interaction from your JavaScript, iOS,
+Android.
+
+The SDK's `connectAndSign` method provides a streamlined approach for dapps to interact with MetaMask.
+This method combines the [`eth_requestAccounts`] and [`personal_sign`] RPC methods, executing them sequentially.
+`connectAndSign` takes one parameter, the message string to be signed, and passes the message and
+the output of [`eth_requestAccounts`] directly to [`personal_sign`].
+
+:::info
+
+Check out the [JSON-RPC API](/wallet/reference/json-rpc-methods) reference for more information.
+
+:::
+
+This method enhances dapp user experience, especially on mobile platforms, by allowing users to
+connect to MetaMask and sign a message in a single interaction, requiring only one switch between
+the mobile dapp and MetaMask Mobile.
+This is useful for various purposes such as authentication and transaction verification.
+
+
+
+
+
+## Prerequisites
+
+- MetaMask SDK set up in your JavaScript dapp.
+
+- MetaMask Mobile version 7.10 or later.
+ Your users must have an updated version of MetaMask Mobile for this feature to work correctly.
+ For older versions of MetaMask, this function may not work as expected.
+
+## Use the `connectAndSign` method
+
+Use the `connectAndSign` method as follows:
+
+```javascript
+const connectAndSign = async () => {
+ try {
+ const signResult = await sdk?.connectAndSign({
+ msg: "Connect + Sign message",
+ })
+ setResponse(signResult)
+ } catch (err) {
+ console.warn("failed to connect..", err)
+ }
+}
+```
+
+To invoke `connectAndSign`:
+
+1. Ensure the `MetaMaskSDK` instance (`sdk` in this context) is properly initialized and available.
+2. Call `connectAndSign` with the message to be signed.
+3. Handle the promise to process the response or catch any errors.
+
+## Examples
+
+The following is an example of using the `connectAndSign` method in a React dapp, integrating it
+into a functional component:
+
+```javascript
+import React, { useState } from "react"
+import { useSDK } from "@metamask/sdk-react"
+
+function MyComponent() {
+ const { sdk } = useSDK()
+ const [signedMessage, setSignedMessage] = useState("")
+
+ const handleConnectAndSign = async () => {
+ try {
+ const message = "Your message here"
+ const signature = await sdk.connectAndSign({ msg: message })
+ setSignedMessage(signature)
+ } catch (error) {
+ console.error("Error in signing:", error)
+ }
+ }
+
+ return (
+
+
+ {signedMessage &&
Signed Message: {signedMessage}
}
+
+ )
+}
+```
+
+For a comprehensive React example, see the `App.tsx` file of the example React dapp.
+
+For examples of using the `connectAndSign` function in Next.js and Vue.js, see the
+[example Next.js dapp](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples/nextjs-demo)
+and [example Vue.js dapp](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples/vuejs)
+in the JavaScript SDK GitHub repository.
+
+
+
+[`eth_requestAccounts`]: /wallet/reference/json-rpc-methods/eth_requestAccounts
+[`personal_sign`]: /wallet/reference/json-rpc-methods/personal_sign
diff --git a/sdk/guides/interact-with-contracts.md b/sdk/guides/interact-with-contracts.md
new file mode 100644
index 00000000000..759510577e7
--- /dev/null
+++ b/sdk/guides/interact-with-contracts.md
@@ -0,0 +1,294 @@
+---
+description: Contract Interactions
+---
+
+# Contract Interactions
+
+This guide covers everything you need to know about interacting with smart contracts using the MetaMask SDK. You'll learn how to:
+- **Read data** from smart contracts
+- **Write data** to smart contracts
+- **Handle contract events**
+- **Manage transaction states**
+- **Handle contract errors**
+
+We provide implementations using both **Wagmi** (recommended) and **vanilla JavaScript**.
+
+### Using Wagmi
+
+Wagmi provides dedicated hooks for contract interactions, making it simple to read and write contract data:
+
+#### Reading Contract Data
+
+```tsx
+import { useReadContract } from 'wagmi'
+
+function TokenBalance() {
+ const {
+ data: balance,
+ isError,
+ isLoading
+ } = useReadContract({
+ address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+ abi: [
+ {
+ name: 'balanceOf',
+ type: 'function',
+ stateMutability: 'view',
+ inputs: [{ name: 'owner', type: 'address' }],
+ outputs: [{ name: 'balance', type: 'uint256' }],
+ },
+ ],
+ functionName: 'balanceOf',
+ args: ['0x03A71968491d55603FFe1b11A9e23eF013f75bCF'],
+ })
+
+ if (isLoading) return
+```
+
+### Best Practices
+
+1. **User Interaction**
+ - Only trigger connection requests in response to user actions (like button clicks)
+ - Never auto-connect on page load
+ - Provide clear feedback during connection states
+
+2. **Error Handling**
+ - Handle common errors like user rejection (code 4001)
+ - Provide clear error messages to users
+ - Fallback gracefully when MetaMask is not installed
+
+3. **Account Changes**
+ - Always listen for account changes
+ - Update your UI when accounts change
+ - Handle disconnection events
+
+4. **Chain Support**
+ - Listen for network/chain changes
+ - Verify the current chain meets your requirements
+ - Provide clear messaging when users need to switch networks
+ - Learn more here: [Network Management](/sdk/guides/network-management)
+
+### Common Errors
+
+| Error Code | Description | Solution |
+|------------|-------------|----------|
+| **4001** | User rejected request | Show a message asking user to approve the connection |
+| **-32002** | Request already pending | Disable connect button while request is pending |
+| **-32603** | Internal JSON-RPC error | Check if MetaMask is properly installed |
+
+### Next Steps
+
+- [Network Management](/sdk/guides/network-management)
+- [Transaction Handling](/sdk/guides/transaction-handling)
+- [Interact with Contracts](/sdk/guides/interact-with-contracts)
\ No newline at end of file
diff --git a/sdk/introduction/llm-prompt.md b/sdk/introduction/llm-prompt.md
new file mode 100644
index 00000000000..12f7c136fac
--- /dev/null
+++ b/sdk/introduction/llm-prompt.md
@@ -0,0 +1,121 @@
+---
+description: LLM Prompt
+---
+
+# LLM prompt
+
+The following text is a condensed introduction to the MetaMask SDK, for use in an LLM's limited context.
+
+Go ahead, copy and paste it into an LLM-based chatbot and see how it works!
+
+```
+You are a helpful assistant with expertise in MetaMask SDK integration. You help developers implement MetaMask wallet connections and blockchain interactions in their applications.
+
+Core Capabilities:
+- Connect to MetaMask wallet (extension or mobile)
+- Read and write data to smart contracts
+- Handle blockchain transactions
+- Manage network connections
+- Work with Web3 standards (EIP-1193, EIP-6963)
+
+Technologies:
+Primary stack (recommended):
+- Wagmi (React hooks for Ethereum)
+- TypeScript
+- React/Next.js
+- Viem (Ethereum interactions)
+
+Alternative approach:
+- Vanilla JavaScript
+- MetaMask provider API
+- EIP-1193 provider interface
+
+Common Patterns:
+
+1. Wallet Connection
+
+Using Wagmi (Recommended):
+ import { useConnect } from 'wagmi'
+
+ function Connect() {
+ const { connect, connectors } = useConnect()
+ return (
+
+ )
+ }
+
+Using Vanilla JS:
+ const provider = window.ethereum;
+ const accounts = await provider.request({
+ method: 'eth_requestAccounts'
+ });
+
+2. Reading Contract Data
+
+Using Wagmi:
+ const { data } = useReadContract({
+ address: contractAddress,
+ abi: contractABI,
+ functionName: 'balanceOf',
+ args: [address],
+ })
+
+Using Vanilla JS:
+ const result = await provider.request({
+ method: 'eth_call',
+ params: [{
+ to: contractAddress,
+ data: encodedFunctionData,
+ }],
+ });
+
+3. Writing to Contracts
+
+Using Wagmi:
+ const { writeContract } = useWriteContract();
+ await writeContract({
+ address: contractAddress,
+ abi: contractABI,
+ functionName: 'mint',
+ args: [tokenId],
+ })
+
+Using Vanilla JS:
+ await provider.request({
+ method: 'eth_sendTransaction',
+ params: [{
+ to: contractAddress,
+ data: encodedFunctionData,
+ }],
+ });
+
+Best Practices:
+1. Always handle errors gracefully
+2. Show clear loading states
+3. Track transaction status
+4. Validate inputs and addresses
+5. Use appropriate gas settings
+6. Consider mobile wallet interactions
+
+Response Guidelines:
+When answering questions:
+1. Prefer Wagmi examples unless vanilla JS is specifically requested
+2. Include error handling in examples
+3. Consider both web and mobile wallet scenarios
+4. Provide TypeScript types where relevant
+5. Include brief explanations with code examples
+6. Consider security implications
+
+Example Usage:
+You can ask questions like:
+- "How do I connect to MetaMask?"
+- "How do I read a token balance?"
+- "How do I send a transaction?"
+- "How do I handle network changes?"
+- "How do I implement wallet disconnection?"
+- "How do I add error handling for contract calls?"
+
+Feel free to ask about specific implementation details, best practices, or troubleshooting.
+```
\ No newline at end of file
diff --git a/sdk/introduction/supported-networks.md b/sdk/introduction/supported-networks.md
new file mode 100644
index 00000000000..af9d3de8343
--- /dev/null
+++ b/sdk/introduction/supported-networks.md
@@ -0,0 +1,30 @@
+---
+description: Supported networks
+---
+
+# Supported networks
+
+## EVM networks
+
+MetaMask SDK works with all EVM-compatible L1/L2 networks:
+
+- Ethereum
+- Linea
+- Base
+- Optimism
+- Polygon
+- Arbitrum
+- Avalanche
+- BNB Chain
+- and [many more](https://chainlist.org/)
+
+:::tip
+For production deployments, it's important to use reliable RPC providers instead of public nodes. We recommend using services like [Infura](https://infura.io/) to ensure better reliability and performance.
+:::
+
+## Non-EVM networks
+
+Some non-EVM networks can work as well via [MetaMask Snaps](https://metamask.io/snaps/).
+
+- Starknet ([learn more here](https://docs.metamask.io/wallet/how-to/use-non-evm-networks/starknet/))
+
diff --git a/sdk/introduction/supported-platforms.md b/sdk/introduction/supported-platforms.md
new file mode 100644
index 00000000000..40c7a264ebb
--- /dev/null
+++ b/sdk/introduction/supported-platforms.md
@@ -0,0 +1,26 @@
+---
+description: Supported platforms
+---
+
+# Supported platforms
+
+MetaMask SDK lets you connect your apps to MetaMask Wallet in the following ways:
+
+- **Desktop web**: Automatically connects to Wallet extension or Wallet mobile app via QR code.
+
+- **Mobile**: Wallet SDK generates a deep link that takes users straight to the Wallet mobile app.
+
+| Dapp Location | User Device | Connection Method | Metamask SDK | Other SDKs |
+|---------------|-------------|------------------|--------------------------|--------------------------|
+| Desktop Web | Wallet Extension | Automatic connection via browser extension | Supported | Supported |
+| Desktop Web | Wallet Mobile App | QR code scan with mobile wallet | Supported | Limited |
+| Mobile Browser | Wallet Mobile App | Deep link directly to mobile wallet app | Supported | Limited |
+| Mobile App | Wallet Mobile App | Deep link directly to mobile wallet app | Supported | Limited |
+
+
+
+:::tip
+
+For better user experience on **mobile**, it's important to use reliable RPC providers instead of public nodes. We recommend using services like [Infura](https://infura.io/) to ensure better reliability and performance.
+
+:::
diff --git a/sdk/introduction/welcome.md b/sdk/introduction/welcome.md
new file mode 100644
index 00000000000..3178a5a4aaa
--- /dev/null
+++ b/sdk/introduction/welcome.md
@@ -0,0 +1,31 @@
+---
+slug: /
+description: Welcome
+---
+
+# Welcome
+
+Welcome to the **MetaMask SDK** developer documentation!
+
+MetaMask SDK is a **toolkit that allows you to build onchain apps** by:
+
+- Authenticating users
+- Managing wallet states
+- Handling transactions
+- Interacting with contracts
+- and many more!
+
+### Why use the SDK?
+
+- Works on multiple platforms
+ - Web - via browser extensions or QR codes for the mobile app
+ - Mobile - via deep links to the mobile app
+- Works with all EVM-compatible L1/L2 networks
+- Handles onboarding of users
+- Battle tested with millions of users on MetaMask
+
+### Where do I start?
+
+- [Install SDK - JavaScript + Wagmi](/sdk/quick-start/javascript-+-wagmi)
+- [Install SDK - JavaScript](/sdk/quick-start/javascript)
+- [Install SDK - React Native](/sdk/quick-start/react-native)
diff --git a/sdk/quick-start/javascript-+-wagmi.md b/sdk/quick-start/javascript-+-wagmi.md
new file mode 100644
index 00000000000..82bca4f84d9
--- /dev/null
+++ b/sdk/quick-start/javascript-+-wagmi.md
@@ -0,0 +1,172 @@
+---
+description: JavaScript + Wagmi (recommended)
+---
+
+# JavaScript + Wagmi (recommended)
+
+Get started with MetaMask SDK in your web application.
+
+This quickstart app demonstrates how to integrate the MetaMask SDK with a [Next.js](https://nextjs.org/) application using [wagmi](https://wagmi.sh/).
+
+
+
+
);
diff --git a/src/components/CardSection.tsx b/src/components/CardSection.tsx
index 9a851a27446..0883b53bdd7 100644
--- a/src/components/CardSection.tsx
+++ b/src/components/CardSection.tsx
@@ -1,36 +1,36 @@
import React from "react";
+import clsx from "clsx";
import Card, { type CardItem } from "@site/src/components/Card";
import styles from "./cardsection.module.css";
const CardList: CardItem[] = [
{
- title: "📱 Integrate your dapp with the MetaMask wallet",
+ title: "Wallet",
+ subtitle: "Integrate with MetaMask Wallet",
link: "/wallet",
description: (
<>
- Integrate your dapp with MetaMask using MetaMask SDK and the Wallet API.
- You can interact with your users' EVM accounts from multiple dapp platforms.
+ Interact with your users' via the MetaMask Wallet API.
),
},
{
- title: "🛠️ Extend the functionality of MetaMask using Snaps",
- link: "/snaps",
+ title: "SDK",
+ subtitle: "Build on chain apps",
+ link: "/sdk",
description: (
<>
- Extend the functionality of MetaMask using Snaps. You can create a Snap
- to add support for custom networks, account types, APIs, and more.
+ Authenticate users, handle transactions, interact with contracts, and more.
),
},
{
- title: "📐 Build and scale your dapp using services",
- link: "/services",
+ title: "Snaps",
+ subtitle: "Extend the functionality of MetaMask",
+ link: "/snaps",
description: (
<>
- Build and scale your dapp or Snap using services provided by MetaMask
- and Infura. This includes APIs that optimize essential development
- tasks.
+ Extend the functionality with custom networks, account types, APIs, and more.
),
},
@@ -38,11 +38,13 @@ const CardList: CardItem[] = [
export default function CardSection(): JSX.Element {
return (
-
-
- Integrate with and extend upon the world's leading self-custodial
- crypto wallet.
+ Build with the world's leading self-custodial crypto wallet.
-
- Get started
-
);
diff --git a/vercel.json b/vercel.json
index f68b497aa3b..18ca0a1f237 100644
--- a/vercel.json
+++ b/vercel.json
@@ -32,103 +32,99 @@
},
{
"source": "/guide/metamask-extension-provider/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/quickstart/javascript/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/quickstart/react/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/quickstart/other-platforms/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/discover-multiple-wallets/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/detect-wallet/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/detect-wallet/multiple-wallets/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/access-provider/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/use-3rd-party-integrations/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/use-sdk/3rd-party-libraries/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/connect/",
- "destination": "/wallet/connect/"
+ "destination": "/wallet/"
},
{
"source": "/wallet/how-to/connect/set-up-sdk/:path*/",
- "destination": "/wallet/connect/metamask-sdk/:path*/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/how-to/use-sdk/:path*/",
- "destination": "/wallet/connect/metamask-sdk/:path*/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/concepts/sdk/",
- "destination": "/wallet/connect/metamask-sdk/"
+ "destination": "/sdk/"
},
{
"source": "/guide/mobile-getting-started/",
- "destination": "/wallet/connect/metamask-sdk/"
+ "destination": "/sdk/"
},
{
"source": "/guide/site-compatibility-checklist/",
- "destination": "/wallet/connect/metamask-sdk/"
+ "destination": "/sdk/"
},
{
"source": "/guide/mobile-best-practices/",
- "destination": "/wallet/connect/metamask-sdk/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/how-to/use-mobile/",
- "destination": "/wallet/connect/metamask-sdk/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/how-to/integrate-with-mobile/",
- "destination": "/wallet/connect/metamask-sdk/"
- },
- {
- "source": "/sdk/",
- "destination": "/wallet/connect/metamask-sdk/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/how-to/connect/set-up-sdk/javascript/react-native/",
- "destination": "/wallet/connect/metamask-sdk/mobile/react-native/"
+ "destination": "/sdk/quick-start/react-native/"
},
{
"source": "/wallet/how-to/use-sdk/javascript/react-native/",
- "destination": "/wallet/connect/metamask-sdk/mobile/react-native/"
+ "destination": "/sdk/quick-start/react-native/"
},
{
"source": "/wallet/how-to/use-sdk/3rd-party-libraries/wagmi/",
- "destination": "/wallet/connect/3rd-party-libraries/wagmi/"
+ "destination": "/sdk/quick-start/javascript-+-wagmi/"
},
{
"source": "/wallet/how-to/use-3rd-party-integrations/web3-onboard/",
- "destination": "/wallet/connect/3rd-party-libraries/web3-onboard/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/how-to/use-sdk/3rd-party-libraries/web3-onboard/",
- "destination": "/wallet/connect/3rd-party-libraries/web3-onboard/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/category/how-to/",
@@ -168,7 +164,7 @@
},
{
"source": "/wallet/how-to/use-sdk/javascript/connect-and-sign/",
- "destination": "/wallet/how-to/sign-data/connect-and-sign/"
+ "destination": "/sdk/guides/advanced/connect-and-sign/"
},
{
"source": "/wallet/how-to/use-siwe/",
@@ -180,15 +176,15 @@
},
{
"source": "/wallet/how-to/use-3rd-party-integrations/js-infura-api/",
- "destination": "/wallet/how-to/make-read-only-requests/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/how-to/use-sdk/javascript/make-read-only-requests/",
- "destination": "/wallet/how-to/make-read-only-requests/"
+ "destination": "/sdk/guides/advanced/batch-requests/"
},
{
"source": "/wallet/how-to/use-sdk/javascript/batch-json-rpc-requests/",
- "destination": "/wallet/how-to/batch-json-rpc-requests/"
+ "destination": "/sdk/guides/advanced/batch-requests/"
},
{
"source": "/guide/registering-your-token/",
@@ -292,7 +288,7 @@
},
{
"source": "/wallet/concepts/sdk/connections/",
- "destination": "/wallet/concepts/sdk-connections/"
+ "destination": "/sdk/"
},
{
"source": "/wallet/concepts/sdk/android/",
diff --git a/wallet-sidebar.js b/wallet-sidebar.js
index 6dfce855f56..2fea02aba73 100644
--- a/wallet-sidebar.js
+++ b/wallet-sidebar.js
@@ -4,135 +4,13 @@
const sidebar = {
walletSidebar: [
{
- type: "doc",
- label: "Introduction",
- id: "index",
- },
- {
- type: "category",
- label: "Connect to MetaMask",
- collapsible: true,
+ type: 'category',
+ label: 'Introduction',
+ collapsible: false,
collapsed: false,
- link: { type: "doc", id: "connect/index" },
items: [
- {
- type: "category",
- label: "MetaMask SDK",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "connect/metamask-sdk/index" },
- items: [
- {
- type: "category",
- label: "JavaScript",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "connect/metamask-sdk/javascript/index" },
- items: [
- {
- type: "category",
- label: "React",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "connect/metamask-sdk/javascript/react/index" },
- items: [
- {
- type: "doc",
- label: "React UI",
- id: "connect/metamask-sdk/javascript/react/react-ui"
- },
- ],
- },
- {
- type: "doc",
- label: "Pure JavaScript",
- id: "connect/metamask-sdk/javascript/pure-js"
- },
- {
- type: "doc",
- label: "Other web frameworks",
- id: "connect/metamask-sdk/javascript/other-web-frameworks"
- },
- {
- type: "doc",
- label: "Node.js",
- id: "connect/metamask-sdk/javascript/nodejs"
- },
- {
- type: "doc",
- label: "Electron",
- id: "connect/metamask-sdk/javascript/electron"
- },
- ],
- },
- {
- type: "category",
- label: "Mobile",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "connect/metamask-sdk/mobile/index" },
- items: [
- {
- type: "doc",
- label: "iOS",
- id: "connect/metamask-sdk/mobile/ios"
- },
- {
- type: "doc",
- label: "Android",
- id: "connect/metamask-sdk/mobile/android"
- },
- {
- type: "doc",
- label: "React Native",
- id: "connect/metamask-sdk/mobile/react-native"
- },
- ],
- },
- {
- type: "category",
- label: "Gaming",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "connect/metamask-sdk/gaming/index" },
- items: [
- {
- type: "doc",
- label: "Unity",
- id: "connect/metamask-sdk/gaming/unity"
- }
- ],
- },
- ],
- },
- {
- type: "category",
- label: "Third-party libraries",
- collapsible: true,
- collapsed: true,
- link: {
- type: "generated-index",
- slug: "/connect/3rd-party-libraries",
- description: "You can connect to MetaMask using third-party libraries that integrate MetaMask SDK."
- },
- items: [
- {
- type: "doc",
- label: "Wagmi",
- id: "connect/3rd-party-libraries/wagmi"
- },
- {
- type: "doc",
- label: "Web3-Onboard",
- id: "connect/3rd-party-libraries/web3-onboard"
- },
- ],
- },
- {
- type: "doc",
- label: "Wallet API",
- id: "connect/wallet-api",
- },
+ 'introduction/welcome',
+ 'introduction/wallet-api',
],
},
{
@@ -173,11 +51,6 @@ const sidebar = {
collapsed: true,
link: { type: "doc", id: "how-to/sign-data/index" },
items: [
- {
- type: "doc",
- label: "Connect and sign",
- id: "how-to/sign-data/connect-and-sign"
- },
{
type: "doc",
label: "Sign in with Ethereum",
@@ -190,16 +63,6 @@ const sidebar = {
label: "Send transactions",
id: "how-to/send-transactions"
},
- {
- type: "doc",
- label: "Make read-only requests",
- id: "how-to/make-read-only-requests"
- },
- {
- type: "doc",
- label: "Batch JSON-RPC requests",
- id: "how-to/batch-json-rpc-requests"
- },
{
type: "category",
label: "Display in MetaMask",
@@ -221,11 +84,6 @@ const sidebar = {
type: "doc",
label: "Display a dapp icon",
id: "how-to/display/icon"
- },
- {
- type: "doc",
- label: "Display custom modals",
- id: "how-to/display/custom-modals"
}
]
},
@@ -290,59 +148,6 @@ const sidebar = {
}
]
},
- {
- type: "category",
- label: "Use the Unity SDK",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "how-to/use-unity-sdk/index" },
- items: [
- {
- type: "doc",
- label: "Connect and sign",
- id: "how-to/use-unity-sdk/connect-and-sign"
- },
- {
- type: "doc",
- label: "Set up Infura",
- id: "how-to/use-unity-sdk/infura"
- },
- {
- type: "category",
- label: "Interact with smart contracts",
- collapsible: true,
- collapsed: true,
- link: { type: "doc", id: "how-to/use-unity-sdk/smart-contracts/index" },
- items: [
- {
- type: "doc",
- label: "Contract interface",
- id: "how-to/use-unity-sdk/smart-contracts/contract-interface"
- },
- {
- type: "doc",
- label: "Contract factory",
- id: "how-to/use-unity-sdk/smart-contracts/contract-factory"
- },
- {
- type: "doc",
- label: "Contract proxy class",
- id: "how-to/use-unity-sdk/smart-contracts/contract-proxy-class"
- },
- {
- type: "doc",
- label: "Contract provider",
- id: "how-to/use-unity-sdk/smart-contracts/contract-provider"
- }
- ]
- },
- {
- type: "doc",
- label: "Enable human-readable addresses",
- id: "how-to/use-unity-sdk/dweb"
- }
- ]
- },
{
type: "doc",
label: "Onboard users",
@@ -367,26 +172,11 @@ const sidebar = {
collapsed: true,
link: { type: "generated-index", slug: "/concepts" },
items: [
- {
- type: "doc",
- label: "Architecture",
- id: "concepts/architecture"
- },
{
type: "doc",
label: "About the Wallet API",
id: "concepts/wallet-api"
},
- {
- type: "doc",
- label: "SDK connections",
- id: "concepts/sdk-connections"
- },
- {
- type: "doc",
- label: "Android SDK architecture",
- id: "concepts/android-sdk"
- },
{
type: "doc",
label: "Convenience libraries",
@@ -431,11 +221,6 @@ const sidebar = {
label: "Create a simple dapp",
id: "tutorials/javascript-dapp-simple",
},
- {
- type: "doc",
- label: "Create a dapp with the SDK and Wagmi",
- id: "tutorials/react-dapp-sdk-wagmi",
- },
],
},
{
@@ -445,16 +230,6 @@ const sidebar = {
collapsed: false,
link: { type: "generated-index", slug: "/reference" },
items: [
- {
- type: "doc",
- label: "JavaScript SDK options",
- id: "reference/sdk-js-options",
- },
- {
- type: "doc",
- label: "Unity SDK API",
- id: "reference/sdk-unity-api",
- },
{
type: "category",
label: "Non-EVM APIs",
diff --git a/wallet/index.md b/wallet/index.md
deleted file mode 100644
index 4153406a008..00000000000
--- a/wallet/index.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-description: Integrate your dapp with the MetaMask wallet.
----
-
-# Integrate your dapp with the MetaMask wallet
-
-Integrate your dapp with MetaMask using **MetaMask SDK** and the **Wallet API**.
-Use MetaMask SDK to create a seamless connection between your dapp and MetaMask across desktop and
-mobile platforms.
-Use the Wallet API to interact with users' EVM accounts in MetaMask.
-
-Get started by [connecting to MetaMask](connect/index.md).
-
-## Why use MetaMask SDK?
-
-**MetaMask SDK** enables a reliable, secure, and seamless connection between your dapp and the
-MetaMask browser extension or MetaMask Mobile, providing cross-platform compatibility with a
-consistent user experience.
-Key benefits include:
-
-- **Multi-platform support** - Connect from web, desktop, mobile, and gaming platforms.
-- **Seamless connections** - Minimize reconnections and improve user experience, especially on mobile.
-- **Mobile-first optimization** - Enable faster wallet interactions with instant deeplinks and advanced features.
-- **Enhanced functionality** - Use [RPC request batching](how-to/batch-json-rpc-requests.md),
- [EIP-6963](/wallet/concepts/wallet-interoperability.md) for wallet discovery, and wallet security enhancements.
-- **Third-party library integration** - Use libraries like [Wagmi](connect/3rd-party-libraries/wagmi.md)
- or [Web3-Onboard](connect/3rd-party-libraries/web3-onboard.md) that integrate SDK support.
-
-The **Wallet API** allows you to interact with users' EVM accounts using standardized JSON-RPC calls.
-While you can connect to the MetaMask extension directly using just the Wallet API, we recommend
-using the SDK or third-party libraries in conjunction with the Wallet API, to take advantage of the
-SDK's benefits.
-
-## Where do I start?
-
-See [**Connect to MetaMask**](connect/index.md) to learn about the different connection options,
-and get started quickly.
-
-## Questions?
-
-For more support, connect with the MetaMask team and community on [Consensys Discord](https://discord.gg/consensys).
-
-:::note MetaMask user support
-For MetaMask user support, visit the [MetaMask Help Center](https://support.metamask.io/).
-:::
diff --git a/wallet/connect/wallet-api.md b/wallet/introduction/wallet-api.md
similarity index 99%
rename from wallet/connect/wallet-api.md
rename to wallet/introduction/wallet-api.md
index 785d6afda86..946e3a3d8f1 100644
--- a/wallet/connect/wallet-api.md
+++ b/wallet/introduction/wallet-api.md
@@ -3,7 +3,7 @@ description: Connect to MetaMask using the Wallet API and EIP-6963.
toc_max_heading_level: 4
---
-# Connect to MetaMask using the Wallet API
+# Wallet API
You can connect your dapp to users' MetaMask wallets by detecting MetaMask in their browsers and
connecting to their accounts.
diff --git a/wallet/introduction/welcome.md b/wallet/introduction/welcome.md
new file mode 100644
index 00000000000..8ea498825a1
--- /dev/null
+++ b/wallet/introduction/welcome.md
@@ -0,0 +1,32 @@
+---
+slug: /
+description: Welcome to the MetaMask Wallet API documentation
+---
+
+# Welcome
+
+Welcome to the **MetaMask Wallet API** documentation!
+
+:::tip Building a cross-platform or mobile app?
+For cross-platform development, mobile integration, or advanced features like QR codes and deep linking, check out the [**MetaMask SDK** docs](https://docs.metamask.io/sdk/).
+:::
+
+## What is the Wallet API?
+
+The Wallet API is MetaMask's core interface for web applications to interact with the MetaMask browser extension. It enables you to:
+
+- Connect web dApps to MetaMask browser extension
+- Interact with users' Ethereum accounts
+- Send transactions and sign messages
+- Listen to account and network changes
+- Use the provider methods
+- Use the JSON-RPC methods
+
+The Wallet API uses standardized JSON-RPC calls to interact with users' EVM accounts and implements standard interfaces like [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) for Ethereum provider methods and [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) for wallet detection.
+
+## Wallet API vs SDK
+
+The **Wallet API** is designed for web applications that connect to the MetaMask browser extension. If you're building a desktop web-only dApp, the Wallet API provides everything you need.
+
+The **MetaMask SDK** builds on top of the Wallet API, adding cross-platform support and features like mobile deep linking and QR code connections. SDK is recommended if you want to build a cross-platform on chain apps.
+
![Switch Networks]({require("../_assets/network.gif").default})
+
+ ![Connect to MetaMask]({require("../_assets/connect.gif").default})
+
+ ![Quickstart]({require("../_assets/quickstart.jpg").default})
+
+