[Delegation Toolkit Add ERC-20 paymaster tutorial (#2259)

AyushBherwani1998 · “AyushBherwani1998” · alexandratran · web-flow · commit 8811d25fbb58 · 2025-09-02T16:38:57.000-07:00
* add erc-20 paymaster tutorial

* merge with main

* fix typo

* improve steps

* edit tutorial

* edit tutorial and change to manual sidebar

---------

Co-authored-by: “AyushBherwani1998” &lt;“ayush.bherwani1998@gmail.com”&gt;
Co-authored-by: Alexandra Tran &lt;alexandratran@protonmail.com&gt;
Co-authored-by: Alexandra Carrillo &lt;12214231+alexandratran@users.noreply.github.com&gt;
diff --git a/delegation-toolkit/concepts/_category_.json b/delegation-toolkit/concepts/_category_.json
diff --git a/delegation-toolkit/concepts/delegation/caveat-enforcers.md b/delegation-toolkit/concepts/delegation/caveat-enforcers.md
@@ -1,6 +1,5 @@
 ---
 description: Learn about caveat enforcers and how they restrict delegations.
-sidebar_position: 2
 ---
 
 # Caveat enforcers
diff --git a/delegation-toolkit/concepts/delegation/index.md b/delegation-toolkit/concepts/delegation/index.md
@@ -1,6 +1,5 @@
 ---
 description: Learn about delegation, the delegation lifecycle, and the Delegation Framework.
-sidebar_position: 2
 toc_max_heading_level: 2
 ---
 
diff --git a/delegation-toolkit/concepts/environment.md b/delegation-toolkit/concepts/environment.md
@@ -1,6 +1,5 @@
 ---
 description: Learn about the delegator environment object `DeleGatorEnvironment` and how to use it.
-sidebar_position: 3
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/concepts/smart-accounts.md b/delegation-toolkit/concepts/smart-accounts.md
@@ -1,6 +1,5 @@
 ---
 description: Learn about MetaMask Smart Accounts.
-sidebar_position: 1
 ---
 
 # MetaMask Smart Accounts
diff --git a/delegation-toolkit/experimental/erc-7710-redeem-delegations.md b/delegation-toolkit/experimental/erc-7710-redeem-delegations.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to redeem ERC-7710 delegations with a smart contract account or an externally owned account (EOA).
-sidebar_position: 3
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/experimental/erc-7715-request-permissions.md b/delegation-toolkit/experimental/erc-7715-request-permissions.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to request ERC-7715 permissions.
-sidebar_position: 2
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/experimental/store-retrieve-delegations.md b/delegation-toolkit/experimental/store-retrieve-delegations.md
@@ -1,8 +1,6 @@
 ---
 description: Store and retrieve delegations using the `DelegationStorageClient`.
-sidebar_position: 1
 toc_max_heading_level: 2
-sidebar_class_name: hidden
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/get-started/_category_.json b/delegation-toolkit/get-started/_category_.json
diff --git a/delegation-toolkit/get-started/erc7715-quickstart.md b/delegation-toolkit/get-started/erc7715-quickstart.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to use ERC-7715 to request permissions.
-sidebar_position: 3
 sidebar_label: ERC-7715 quickstart
 ---
 
diff --git a/delegation-toolkit/get-started/install.md b/delegation-toolkit/get-started/install.md
@@ -1,7 +1,6 @@
 ---
 sidebar_label: Install and set up
 description: Learn how to install and set up the MetaMask Delegation Toolkit.
-sidebar_position: 1
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/get-started/smart-account-quickstart/eip7702.md b/delegation-toolkit/get-started/smart-account-quickstart/eip7702.md
@@ -1,6 +1,5 @@
 ---
 description: Upgrade an externally owned account (EOA) to a smart account
-sidebar_position: 1
 sidebar_label: EIP-7702 quickstart
 ---
 
diff --git a/delegation-toolkit/get-started/smart-account-quickstart/index.md b/delegation-toolkit/get-started/smart-account-quickstart/index.md
@@ -1,6 +1,5 @@
 ---
 description: Get started quickly with the MetaMask Smart Accounts
-sidebar_position: 2
 sidebar_label: Smart account quickstart
 ---
 
diff --git a/delegation-toolkit/get-started/supported-networks.md b/delegation-toolkit/get-started/supported-networks.md
@@ -2,7 +2,6 @@
 title: Supported networks
 sidebar_label: Supported networks
 description: Supported networks for Delegation Toolkit.
-sidebar_position: 5
 ---
 
 The following tables display the networks supported by each version of the MetaMask Delegation Toolkit.
diff --git a/delegation-toolkit/get-started/use-the-cli.md b/delegation-toolkit/get-started/use-the-cli.md
@@ -1,6 +1,5 @@
 ---
 description: Get started with the MetaMask Delegation Toolkit using the `@metamask/create-gator-app` CLI.
-sidebar_position: 4
 sidebar_label: Use the CLI
 ---
 
diff --git a/delegation-toolkit/guides/_category_.json b/delegation-toolkit/guides/_category_.json
diff --git a/delegation-toolkit/guides/configure.md b/delegation-toolkit/guides/configure.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to configure the MetaMask Delegation Toolkit using Viem.
-sidebar_position: 1
 sidebar_label: Configure the toolkit
 ---
 
diff --git a/delegation-toolkit/guides/delegation/_category_.json b/delegation-toolkit/guides/delegation/_category_.json
diff --git a/delegation-toolkit/guides/delegation/execute-on-smart-accounts-behalf.md b/delegation-toolkit/guides/delegation/execute-on-smart-accounts-behalf.md
@@ -1,6 +1,5 @@
 ---
 description: Use delegations to perform executions on a smart account's behalf.
-sidebar_position: 1
 sidebar_label: Execute on a smart account's behalf
 ---
 
diff --git a/delegation-toolkit/guides/delegation/restrict-delegation.md b/delegation-toolkit/guides/delegation/restrict-delegation.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to restrict a delegation using caveat enforcers, and the available caveat types.
-sidebar_position: 2
 toc_max_heading_level: 3
 ---
 
diff --git a/delegation-toolkit/guides/smart-accounts/_category_.json b/delegation-toolkit/guides/smart-accounts/_category_.json
diff --git a/delegation-toolkit/guides/smart-accounts/create-smart-account.md b/delegation-toolkit/guides/smart-accounts/create-smart-account.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to create a MetaMask smart account using Delegation Toolkit.
-sidebar_position: 1
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/guides/smart-accounts/generate-multisig-signature.md b/delegation-toolkit/guides/smart-accounts/generate-multisig-signature.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to generate a Multisig signature.
-sidebar_position: 4
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/guides/smart-accounts/send-gasless-transaction.md b/delegation-toolkit/guides/smart-accounts/send-gasless-transaction.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to send a gasless transaction
-sidebar_position: 3
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/guides/smart-accounts/send-user-operation.md b/delegation-toolkit/guides/smart-accounts/send-user-operation.md
@@ -1,6 +1,5 @@
 ---
 description: Learn how to send an ERC-4337 user operation using Viem.
-sidebar_position: 2
 ---
 
 import Tabs from "@theme/Tabs";
diff --git a/delegation-toolkit/index.md b/delegation-toolkit/index.md
@@ -2,7 +2,6 @@
 title: Delegation Toolkit introduction
 sidebar_label: Introduction
 description: High-level overview of Smart Accounts and the Delegation Toolkit.
-sidebar_position: 1
 ---
 
 import CardList from "@site/src/components/CardList"
diff --git a/delegation-toolkit/reference/_category_.json b/delegation-toolkit/reference/_category_.json
diff --git a/delegation-toolkit/reference/api/_category_.json b/delegation-toolkit/reference/api/_category_.json
diff --git a/delegation-toolkit/reference/api/delegation.md b/delegation-toolkit/reference/api/delegation.md
@@ -1,7 +1,6 @@
 ---
 description: Delegation-related API methods reference.
 sidebar_label: Delegation
-sidebar_position: 1
 toc_max_heading_level: 2
 ---
 
diff --git a/delegation-toolkit/reference/api/experimental-actions/_category_.json b/delegation-toolkit/reference/api/experimental-actions/_category_.json
diff --git a/delegation-toolkit/reference/api/experimental-actions/bundler-client.md b/delegation-toolkit/reference/api/experimental-actions/bundler-client.md
@@ -1,7 +1,6 @@
 ---
 description: Bundler Client API methods reference.
 sidebar_label: Bundler Client
-sidebar_position: 1
 toc_max_heading_level: 2
 ---
 
diff --git a/delegation-toolkit/reference/api/experimental-actions/wallet-client.md b/delegation-toolkit/reference/api/experimental-actions/wallet-client.md
@@ -1,7 +1,6 @@
 ---
 description: Wallet Client API methods reference.
 sidebar_label: Wallet Client
-sidebar_position: 2
 toc_max_heading_level: 2
 ---
 
diff --git a/delegation-toolkit/reference/api/smart-account.md b/delegation-toolkit/reference/api/smart-account.md
@@ -1,7 +1,6 @@
 ---
 description: MetaMask Smart Accounts-related API methods reference.
 sidebar_label: MetaMask Smart Accounts
-sidebar_position: 2
 toc_max_heading_level: 2
 ---
 
diff --git a/delegation-toolkit/reference/caveats.md b/delegation-toolkit/reference/caveats.md
@@ -1,6 +1,5 @@
 ---
 description: Caveat enforcers reference.
-sidebar_position: 1
 toc_max_heading_level: 2
 ---
 
diff --git a/delegation-toolkit/tutorials/use-erc20-paymaster.md b/delegation-toolkit/tutorials/use-erc20-paymaster.md
@@ -0,0 +1,153 @@
+---
+description: Follow this tutorial to use an ERC-20 paymaster with MetaMask Smart Accounts.
+---
+
+# Use an ERC-20 paymaster
+
+This tutorial walks you through using an ERC-20 paymaster with [MetaMask Smart Accounts](../concepts/smart-accounts), enabling users to pay gas fees in USDC.
+This tutorial uses Pimlico's paymaster, but you can use any paymaster of your choice.
+
+## About paymasters
+
+A paymaster is an important component of the [account abstraction (ERC-4337)](../concepts/smart-accounts.md) standard, responsible for abstracting gas fees for end users. 
+There are different types of paymasters, such as gasless paymasters and ERC-20 paymasters. 
+While a gasless paymaster covers the transaction on behalf of the user, an ERC-20 paymaster allows users to pay gas fees using a supported ERC-20 token.
+This removes the need for users to hold native tokens, allowing them to perform onchain actions using only stablecoins.
+
+## Prerequisites
+
+- [Install and set up the Delegation Toolkit](../get-started/install) in your project.
+- [Configure the Delegation Toolkit](../guides/configure).
+- [Create a Hybrid smart account](../guides/smart-accounts/create-smart-account), and fund it with some Sepolia USDC to pay gas fees.
+  :::note
+  You can use [Circle's faucet](https://faucet.circle.com/) to get Sepolia USDC.
+  :::
+- [Create a Pimlico API key](https://docs.pimlico.io/guides/create-api-key#create-api-key).
+
+## Steps
+
+### 1. Create a Public Client
+
+Create a [Viem Public Client](https://viem.sh/docs/clients/public) using Viem's `createPublicClient` function.
+You will configure a smart account and Bundler Client with the Public Client, which you can use to query the signer's account state and interact with the blockchain network.
+
+```typescript
+import { createPublicClient, http } from "viem";
+import { sepolia as chain } from "viem/chains";
+
+const publicClient = createPublicClient({
+  chain,
+  transport: http(),
+});
+```
+
+### 2. Create a Paymaster Client
+
+Create a [Viem Paymaster Client](https://viem.sh/account-abstraction/clients/paymaster)
+using Viem's `createPaymasterClient` function. This client interacts with the paymaster service, enabling users to pay gas fees in USDC.
+
+Replace `<YOUR-API-KEY>` with your Pimlico API key:
+
+```typescript
+import { createPaymasterClient } from "viem/account-abstraction";
+
+const paymasterClient = createPaymasterClient({
+  transport: http("https://api.pimlico.io/v2/11155111/rpc?apikey=<YOUR-API-KEY>"),
+});
+```
+
+### 3. Create a Bundler Client
+
+Create a [Viem Bundler Client](https://viem.sh/account-abstraction/clients/bundler) using Viem's `createBundlerClient` function. You can use the bundler service to estimate gas for user operations and submit transactions to the network.
+
+To use the ERC-20 paymaster, configure the `paymasterContext` with the ERC-20 token you wish to use to pay for gas fees.
+For this tutorial, specify the Sepolia USDC token address.
+
+```typescript
+import { createBundlerClient } from "viem/account-abstraction";
+
+// USDC address on Ethereum Sepolia.
+const token = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
+
+const bundlerClient = createBundlerClient({
+  client: publicClient,
+  transport: http("https://your-bundler-rpc.com"),
+  paymasterContext: {
+    token,
+  }
+});
+```
+
+### 4. Create a Hybrid smart account
+
+Configure the same [Hybrid smart account](../guides/smart-accounts/create-smart-account.md#create-a-hybrid-smart-account) that you created and funded as a [prerequisite](#prerequisites).
+A Hybrid smart account is a flexible smart account implementation that supports both an externally owned account (EOA) owner and any number of passkey (WebAuthn) signers.
+
+```typescript
+import { Implementation, toMetaMaskSmartAccount } from "@metamask/delegation-toolkit";
+import { privateKeyToAccount } from "viem/accounts";
+
+const account = privateKeyToAccount("0x...");
+
+const smartAccount = await toMetaMaskSmartAccount({
+  client: publicClient,
+  implementation: Implementation.Hybrid,
+  deployParams: [account.address, [], [], []],
+  deploySalt: "0x",
+  signatory: { account },
+});
+```
+
+### 5. Send a user operation
+
+The ERC-20 paymaster works by transferring the token from the smart account, and reimbursing itself for paying the gas fees on the user's behalf.
+
+To send a user operation with the ERC-20 paymaster, use the [`sendUserOperation`](https://viem.sh/account-abstraction/actions/bundler/sendUserOperation) method from the Bundler Client.
+You must include a call approving the ERC-20 token to be used by the paymaster.
+To modify the token allowance for the paymaster, perform a write operation on the USDC contract.
+For this tutorial, set an allowance of 10 USDC tokens.
+
+:::note
+In a production dapp, you should first check the existing token allowance and only approve the amount required by the paymaster.
+:::
+
+Batch the approve call with other onchain actions you want to perform using the ERC-20 paymaster.
+Pass the `paymasterClient` from [Step 2](#2-create-a-paymaster-client) to the `paymaster` property.
+
+```typescript
+// Appropriate fee per gas must be determined for the specific bundler being used.
+const maxFeePerGas = 1n;
+const maxPriorityFeePerGas = 1n;
+
+const pimlicoPaymasterAddress = "0x777777777777AeC03fd955926DbF81597e66834C";
+
+// 10 USDC in wei format. Since USDC has 6 decimals, the wei value is 10 * 10^6.
+const approvalAmount = 10000000n;
+
+const userOperationHash = await bundlerClient.sendUserOperation({
+  account: smartAccount,
+  calls: [
+    // USDC approve call
+    {
+      // USDC token address
+      to: token,
+      abi: parseAbi(["function approve(address,uint)"]),
+      functionName: "approve",
+      args: [pimlicoPaymasterAddress, approvalAmount],
+    }
+    // Batch the approve call with other onchain actions.
+    {
+      to: "0x1234567890123456789012345678901234567890",
+      value: parseEther("1"),
+    },
+  ],
+  maxFeePerGas,
+  maxPriorityFeePerGas,
+  paymaster: paymasterClient,
+});
+```
+
+## Next steps
+
+- See [Create a MetaMask smart account](../guides/smart-accounts/create-smart-account.md) to learn more about smart account implementations. 
+- See [Send a gasless transaction](../guides/smart-accounts/send-gasless-transaction.md) to learn how to use gasless paymaster.
diff --git a/gator-sidebar.js b/gator-sidebar.js
diff --git a/vercel.json b/vercel.json
