pimlicolabs · plusminushalf · May 21, 2026 · May 22, 2026 · May 22, 2026
diff --git a/docs/pages/guides/eip7702/faqs.mdx b/docs/pages/guides/eip7702/faqs.mdx
@@ -1,5 +1,7 @@
 # EIP-7702 FAQs
 
+Answers to common questions about EIP-7702 — what it is, how it relates to ERC-4337, which chains Pimlico supports it on, and how EOAs transition into smart accounts under the new transaction type.
+
 ## What is EIP-7702? 
 
 EIP-7702 is a proposal that allows EOAs to become smart accounts. It is going live in the Pectra hard fork on Ethereum Mainnet on May 7, but it is already live on some other chains like BSC Mainnet and Odyssey Testnet.

diff --git a/docs/pages/guides/eip7702/index.mdx b/docs/pages/guides/eip7702/index.mdx
@@ -1,6 +1,6 @@
 # EIP-7702
 
-EIP-7702 is a proposal set for inclusion in the upcoming 2025 Pectra hardfork. The proposal introduces a new transaction type that allows EOA's to assign a "delegation designator" to their account. The delegation designator points to a smart contract and when a transaction is sent to the EOA, it executes the code at the designated address.
+EIP-7702 is a transaction type — shipped as part of the Pectra hardfork that activated on Ethereum mainnet in May 2025 — that lets EOAs assign a "delegation designator" pointing to a smart contract. Once set, transactions sent to the EOA execute the code at the designated address.
 
 This unlocks huge benefits for EOAs, as they can now access smart account features such as batching transactions, gas sponsorships, passkeys as signers, and more.
 

diff --git a/docs/pages/guides/how-to/accounts/comparison.mdx b/docs/pages/guides/how-to/accounts/comparison.mdx
@@ -1,6 +1,6 @@
 # Difference between various Smart Account types in permissionless.js
 
-permissionless.js supports 8 types of accounts. Below is an overview of each account type and their key features:
+permissionless.js supports 8 ERC-4337 smart account implementations — Safe, Kernel, Nexus, Simple Smart Account, LightAccount, TrustWallet, Etherspot, and Thirdweb. This page compares each one by its key features so you can pick the right account for your application.
 
 1. **Safe**
 2. **Kernel**

diff --git a/docs/pages/guides/how-to/accounts/use-coinbase-account.mdx b/docs/pages/guides/how-to/accounts/use-coinbase-account.mdx
@@ -1,8 +1,7 @@
 # How to create and use a Coinbase smart account with permissionless.js
 
+Coinbase smart wallet accounts are supported natively by viem. We recommend using the native viem implementation for which the documentation [can be found here](https://viem.sh/account-abstraction/accounts/smart/toCoinbaseSmartAccount).
 
 :::warning[Warning]
 You should still use permissionless to fetch gas prices. As the bundler might not accept the prices fetched from viem. To learn how to use permissionless to fetch gas prices, [check out this guide](/references/permissionless/reference/pimlico-actions/getUserOperationGasPrice#getuseroperationgasprice).
 :::
-
-Coinbase smart wallet accounts are supported natively by viem. We recommend using the native viem implementation for which the documentation [can be found here](https://viem.sh/account-abstraction/accounts/smart/toCoinbaseSmartAccount).
diff --git a/docs/pages/guides/how-to/accounts/use-kernel-account.mdx b/docs/pages/guides/how-to/accounts/use-kernel-account.mdx
@@ -1,11 +1,11 @@
 # How to create and use a Kernel account with permissionless.js
 
+[Kernel](https://github.com/zerodevapp/kernel) is a **modular smart account** that supports plugins, which are smart contracts that extend the account's functionalities.  You can use Kernel with popular plugins such as session keys and account recovery, and even write your own plugins.  Kernel is compatible with [ERC-7579](https://erc7579.com/).
+
 :::info
 ZeroDev, the author of Kernel, maintains their own in-house SDK built closely on top of permissionless.js that you can use for the account system while still plugging in all the other components from permissionless.js. Take a look at [their documentation](https://docs.zerodev.app) for more information.
 :::
 
-[Kernel](https://github.com/zerodevapp/kernel) is a **modular smart account** that supports plugins, which are smart contracts that extend the account's functionalities.  You can use Kernel with popular plugins such as session keys and account recovery, and even write your own plugins.  Kernel is compatible with [ERC-7579](https://erc7579.com/).
-
 ## Picking an EntryPoint
 
 Kernel is compatible with EntryPoint versions v0.6 and v0.7.

diff --git a/docs/pages/guides/how-to/accounts/use-metamask-account.mdx b/docs/pages/guides/how-to/accounts/use-metamask-account.mdx
@@ -1,11 +1,11 @@
 # How to use MetaMask Smart Accounts with permissionless.js
 
+The [MetaMask Delegation Toolkit](https://docs.metamask.io/delegation-toolkit/get-started/quickstart) is a collection of tools for creating MetaMask Smart Accounts. A smart account can delegate to another signer with granular permission sharing. It is built over [ERC-7710](https://eip.tools/eip/7710) and [ERC-7715](https://eip.tools/eip/7715) to support a standardized minimal interface. Requesting ERC-7715 permissions and redeeming ERC-7710 delegations are experimental features.
+
 :::info
 MetaMask maintains their own in-house SDK built closely on top of viem that you can use for the account system while still plugging in all the other components from permissionless.js. Take a look at [their documentation](https://docs.metamask.io/delegation-toolkit/how-to/send-user-operation) for more information.
 :::
 
-The [MetaMask Delegation Toolkit](https://docs.metamask.io/delegation-toolkit/get-started/quickstart) is a collection of tools for creating MetaMask Smart Accounts. A smart account can delegate to another signer with granular permission sharing. It is built over [ERC-7710](https://eip.tools/eip/7710) and [ERC-7715](https://eip.tools/eip/7715) to support a standardized minimal interface. Requesting ERC-7715 permissions and redeeming ERC-7710 delegations are experimental features.
-
 There are two types of accounts involved in delegation:
 
 1. **Delegator account**: A smart account that supports programmable account behavior and advanced features such as multi-signature approvals, automated transaction batching, and custom security policies.

diff --git a/docs/pages/guides/how-to/accounts/use-thirdweb-account.mdx b/docs/pages/guides/how-to/accounts/use-thirdweb-account.mdx
@@ -1,5 +1,7 @@
 # How to create and use a Thirdweb account with permissionless.js
 
+[Thirdweb](https://thirdweb.com) provides a managed smart account implementation that integrates with their developer platform. This guide walks through creating a Thirdweb smart account with permissionless.js and sending user operations through a bundler and optional paymaster.
+
 ## Picking an EntryPoint
 
 Thirdweb is compatible with EntryPoint versions v0.6 and v0.7. In this guide, we will use EntryPoint v0.7.

diff --git a/docs/pages/guides/how-to/accounts/use-trustwallet-account.mdx b/docs/pages/guides/how-to/accounts/use-trustwallet-account.mdx
@@ -1,14 +1,14 @@
 # How to create and use a Trust smart account with permissionless.js
 
+Trust Wallet is one of the most trusted wallet provider empowering more than 122 million users and is the first Web3 wallet to be [certified by ISO](https://trustwallet.com/security).
+After thorough development and extensive security audits, Trust Wallet launched the [Smart Wallet](https://trustwallet.com/swift) powered by account abstraction.
+
 :::info
 [Trust Wallet](https://trustwallet.com/), the author of [Barz](https://github.com/trustwallet/barz), provides a smart contract security monitoring service for each and every Barz deployed on-chain including Barz created by SDK.
 This is a service that TrustWallet provides to builders to build innovative products on top of a secure foundation.
 Monitoring will automatically start as soon as the Barz account is deployed on-chain; for projects wanting to get security monitoring information, reach out to the smart wallet channel in [TrustWallet Discord](https://discord.gg/trustwallet).
 :::
 
-Trust Wallet is one of the most trusted wallet provider empowering more than 122 million users and is the first Web3 wallet to be [certified by ISO](https://trustwallet.com/security).
-After thorough development and extensive security audits, Trust Wallet launched the [Smart Wallet](https://trustwallet.com/swift) powered by account abstraction.
-
 With the recent opensource of their Smart Wallet system Barz, their smart account solution, together with their security infrastructure is disclosed for public to support builders build products on a secure foundation.
 
 This guide will walk you through how to create and use a Barz account with permissionless.js

diff --git a/docs/pages/guides/how-to/erc20-paymaster/architecture.mdx b/docs/pages/guides/how-to/erc20-paymaster/architecture.mdx
@@ -1,5 +1,7 @@
 # ERC-20 Paymaster Architecture
 
+This page explains the design of Pimlico's ERC-20 Paymaster — an ERC-4337 paymaster that pays user gas fees in exchange for ERC-20 tokens drawn from the user — including the off-chain pricing API and the formula used to estimate the token cost of a user operation.
+
 :::info
 You can view the whole ERC-20 Paymaster contract [in our repository](https://github.com/pimlicolabs).
 

diff --git a/docs/pages/guides/how-to/erc20-paymaster/faqs.mdx b/docs/pages/guides/how-to/erc20-paymaster/faqs.mdx
@@ -1,5 +1,7 @@
 # ERC-20 Paymaster FAQs
 
+Answers to common questions about Pimlico's ERC-20 Paymaster — what a paymaster is, how the ERC-20 variant works, which tokens and chains are supported, and how fees are charged.
+
 ## What is a paymaster?
 
 A Paymaster is a special smart contract under the [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) specification that user operations are able to delegate the responsibility of gas fee payments to. This means that ERC-4337 smart contract wallets no longer need to necessarily be responsible for directly paying gas fees in ETH. The paymaster contracts are able to use custom logic (with certain limitations) to decide whether or not they are willing to sponsor a user operation.

diff --git a/docs/pages/guides/how-to/erc20-paymaster/index.mdx b/docs/pages/guides/how-to/erc20-paymaster/index.mdx
@@ -1,9 +1,9 @@
 # ERC-20 Paymaster
 
-![Landscape](/erc20paymaster.png)
-
 Pimlico's ERC-20 Paymaster is a ERC-4337 paymaster that is able to pay for the gas fees of your users in exchange for ERC-20 tokens.
 
+![Landscape](/erc20paymaster.png)
+
 ## Tutorials
 
 Learning-oriented lessons that take you through a series of steps to complete a project. Most useful when you want to get started with Pimlico. They all involve the Alto Bundler.

diff --git a/docs/pages/guides/how-to/gas-programs/gas-program.mdx b/docs/pages/guides/how-to/gas-programs/gas-program.mdx
@@ -1,11 +1,11 @@
 # How to create a gas program on Pimlico
 
+If you are a chain operator and you would like to be able to easily give out and track gas credits to developers building on your chain, you can create and manage a gas station program using Pimlico sponsorship policies.
+
 :::info
 This guide is for chain operators who want to create a gas program on Pimlico. If you are a developer looking to use a gas program made by someone else or looking to sponsor your own user operations, you should instead look in the [sponsorship policies guide](/guides/how-to/sponsorship-policies).
 :::
 
-If you are a chain operator and you would like to be able to easily give out and track gas credits to developers building on your chain, you can create and manage a gas station program using Pimlico sponsorship policies.
-
 ::::steps
 
 ### Create a Pimlico account
@@ -48,4 +48,4 @@ After you have created the policy, you should see a page where you can copy a li
 To use the policy, the grantee will need to have a Pimlico account and will need to click on the link to claim the authorization, and will then be able to use that authorization to pay for gas on your chain as if it was a policy that they owned. More information about using sponsorship policies can be found in the [relevant guide](/guides/how-to/sponsorship-policies).
 
 
-::::
+::::
diff --git a/docs/pages/guides/how-to/gas-programs/use.mdx b/docs/pages/guides/how-to/gas-programs/use.mdx
@@ -1,5 +1,7 @@
 # How to use the claimed gas grant
 
+Once you have claimed a gas grant from a chain operator's gas program, you can apply it like any other sponsorship policy. This guide shows how to wire the claimed sponsorship policy ID into user operations with permissionless.js so the grant covers gas costs.
+
 ## Usage of Sponsorship Policies with permisionless.js
 
 If you are using [permissionless.js](/references/permissionless), you can use the `PimlicoPaymasterClient` to use sponsorship policies.

diff --git a/docs/pages/guides/how-to/migration-guide.mdx b/docs/pages/guides/how-to/migration-guide.mdx
@@ -1,5 +1,7 @@
 # Migration Guide
 
+This guide walks through the breaking changes and steps required to upgrade permissionless.js between major versions, starting with the migration from `^0.1.0` to `0.2.0`.
+
 ## 0.2.0
 
 :::warning

diff --git a/docs/pages/guides/how-to/parallel-transactions.mdx b/docs/pages/guides/how-to/parallel-transactions.mdx
@@ -1,6 +1,6 @@
 # How to send multiple user operations in parallel
 
-permissionless.js library lets you to send multiple transactions in parallel. This can be useful if you want to batch multiple calls in a single user operation or if you want to send user operations concurrently.
+permissionless.js library lets you send multiple transactions in parallel. This can be useful if you want to batch multiple calls in a single user operation or if you want to send user operations concurrently.
 
 ## Batching Multiple Calls
 

diff --git a/docs/pages/guides/how-to/paymasters/conditional-sponsoring.mdx b/docs/pages/guides/how-to/paymasters/conditional-sponsoring.mdx
@@ -1,9 +1,6 @@
 # How to conditionally sponsor a user operation
 
-With permissionless.js and Viem, you can conditionally sponsor a user operation. This can be useful in situations like:
-
-- Sponsor only first 10 transactions
-- Sponsor if they have a specific NFT
+With permissionless.js and viem, you can conditionally sponsor a user operation — useful when you want to cap free sponsorship to the first N transactions per user, gate it behind ownership of a specific NFT, or apply any other custom rule.
 
 Let's take an example where you want to sponsor only the first 10 transactions.
 

diff --git a/docs/pages/guides/how-to/security/protect-api-keys.mdx b/docs/pages/guides/how-to/security/protect-api-keys.mdx
@@ -1,10 +1,6 @@
 # How to Protect Your API Keys
 
-Keeping your API keys secure is essential. Here are three main ways to protect them:
-
-- Restrict access to your API keys.
-- Use sponsorship policies.
-- Use a proxy server to handle requests to Pimlico.
+Pimlico API keys grant access to your sponsorship balance and paid endpoints, so keeping them secure is essential. This guide covers three ways to protect them — restricting access by IP, user agent, and origin, using sponsorship policies to cap spend, and routing requests through a proxy server you control.
 
 ## Restrict Access to Your API Keys
 

diff --git a/docs/pages/guides/how-to/sponsorship-policies/index.mdx b/docs/pages/guides/how-to/sponsorship-policies/index.mdx
@@ -1,5 +1,7 @@
 # How to use Sponsorship Policies
 
+Sponsorship policies let you define custom rules and limits that govern when the verifying paymaster sponsors a user operation, such as global caps, per-user limits, and per-operation limits. This guide walks through creating a policy in the Pimlico dashboard and applying it to user operations with permissionless.js.
+
 ## What are Sponsorship Policies?
 
 Sponsorship Policies are hosted policies that allow you to define custom rules for sponsorships.

diff --git a/docs/pages/guides/how-to/testing/docker.mdx b/docs/pages/guides/how-to/testing/docker.mdx
@@ -1,11 +1,6 @@
 # Local Testing With Docker
 
-This guide introduces a ready-to-use mock test environment, that contains:
-
-- A local Alto bundler
-- A mock paymaster
-- An Anvil node
-- ERC-4337 related contracts, including the EntryPoint and account factories for all major smart account implementations
+This guide walks you through a ready-to-use Docker-based mock ERC-4337 test environment that bundles a local Alto bundler, a mock paymaster, an Anvil node, and all ERC-4337 related contracts — the EntryPoint and account factories for every major smart account implementation.
 
 The test environment is orchestrated using **docker compose**. Where the docker containers are pulled from [this repo](https://github.com/pimlicolabs/mock-aa-environment).
 

diff --git a/docs/pages/guides/how-to/testing/prool.mdx b/docs/pages/guides/how-to/testing/prool.mdx
@@ -1,10 +1,10 @@
 # Prool
 
-This guide introduces how to setup and run tests in a mock environment using [Prool](https://github.com/wevm/prool).
+This guide walks through setting up and running tests against a mock ERC-4337 environment using [Prool](https://github.com/wevm/prool) — a library by Wevm that lets you programmatically interact with Ethereum server instances like nodes, bundlers, and paymasters.
 
-# Overview
+## Overview
 
-Prool is a library by [Wevm](https://github.com/wevm/viem) that lets you programmatically interact with Ethereum server instances like Nodes, Bundlers, and Paymasters.
+We will be using [Vitest](https://vitest.dev/) as our testing framework and we will be testing against a fork of Base Mainnet.
 
 We will be using [Vitest](https://vitest.dev/) as our testing framework and we will be testing against a fork of Base Mainnet.
 

diff --git a/docs/pages/guides/supported-chains.mdx b/docs/pages/guides/supported-chains.mdx
@@ -1,6 +1,8 @@
 
 # Supported Chains
 
+Pimlico's bundler and paymaster infrastructure is available across dozens of EVM mainnets and testnets. This page lists every supported chain and shows how to target one in your API requests.
+
 All API calls must use the JSON-RPC format and be sent to the following URL:
 
 ```
@@ -15,7 +17,7 @@ For example to access Base, both of these endpoints will work:
 
 You can also access the public endpoint without an API key ([more info](/references/bundler/public-endpoint)).
 
-# Pimlico supports the following chains:
+## Pimlico supports the following chains:
 
 import SupportedChains from "../../../data/supported-chains.md"
 import ChainDetails from "../../../data/chain-details.md";

diff --git a/docs/pages/guides/tutorials/tutorial-2.mdx b/docs/pages/guides/tutorials/tutorial-2.mdx
@@ -1,11 +1,11 @@
 # Tutorial 2 — Submit a user operation with an ERC-20 Paymaster
 
+In this tutorial, you will deploy an ERC-4337 smart contract wallet on Base Sepolia, and submit a user operation that pays for its gas fees with USDC using an ERC-20 Paymaster.
+
 :::info
 You can visit our [ERC-20 Paymaster overview page](/references/paymaster/erc20-paymaster) to learn more about the design and architecture of our ERC-20 Paymaster, and the deployed smart contract addresses.
 :::
 
-In this tutorial, you will deploy an ERC-4337 smart contract wallet on Base Sepolia, and submit a user operation that pays for its gas fees with USDC using an ERC-20 Paymaster.
-
 ## Steps
 
 ::::steps

diff --git a/docs/pages/references/bundler/bundler-errors/invalid-discriminator-value.mdx b/docs/pages/references/bundler/bundler-errors/invalid-discriminator-value.mdx
@@ -1,11 +1,11 @@
 # Validation error: Invalid discriminator value
 
+If you see an error similar to the one above, it means you are calling a method on the Pimlico API that is not supported. The most common reason for this is using the Pimlico API endpoint for standard public Ethereum JSON-RPC methods. As a reminder, the Pimlico API only supports bundler and paymaster methods.
+
 ```txt
 Validation error: Invalid discriminator value. Expected 'eth_chainId' | 'eth_supportedEntryPoints' | 'eth_coinbase' | 'eth_estimateUserOperationGas' | 'eth_sendUserOperation' | 'eth_getUserOperationByHash' | 'eth_getUserOperationReceipt' | 'pm_supportedEntryPoints' | 'pm_sponsorUserOperation' | 'web3_clientVersion' | 'pimlico_getUserOperationStatus' | 'pimlico_getUserOperationGasPrice' | 'pimlico_getBalance' | 'pm_validateSponsorshipPolicies' at \"method\""
 ```
 
-If you see an error similar to the one above, it means you are calling a method on the Pimlico API that is not supported. The most common reason for this is using the Pimlico API endpoint for standard public Ethereum JSON-RPC methods. As a reminder, the Pimlico API only supports bundler and paymaster methods.
-
 ## Possible solutions
 
 Make sure you are using a standard RPC endpoint for public Ethereum methods and the Pimlico API endpoint for Pimlico-specific methods.

diff --git a/docs/pages/references/bundler/bundler-errors/unknown-error.mdx b/docs/pages/references/bundler/bundler-errors/unknown-error.mdx
@@ -1,7 +1,7 @@
 # Unknown error from alto bundler
 
-The bundler encountered an unexpected error. This is either an internal 500 error, or an error with sensitive information that can not returned.
+The bundler encountered an unexpected error. This is either an internal 500 error, or an error with sensitive information that cannot be returned.
 
 ## Possible solutions
 
-- [Reach out to us](https://t.me/pimlicoHQ) if you see this error.
+- [Reach out to us](https://t.me/pimlicoHQ) if you see this error.
diff --git a/docs/pages/references/bundler/endpoints/pimlico_getUserOperationStatus.mdx b/docs/pages/references/bundler/endpoints/pimlico_getUserOperationStatus.mdx
@@ -1,6 +1,6 @@
 # pimlico_getUserOperationStatus
 
-This method takes in a user operation hash and returns the status of the operation and, optionally, the transaction hash the bundler is using to bundle the user operation on-chain. The status can be one of the following:
+This method takes a user operation hash and returns the current status of the operation along with, when relevant, the transaction hash the bundler is using to bundle it on-chain — covering states like not found, not yet submitted, submitted, included, rejected, failed, and queued.
 
 
 | result   | response includes transaction hash | description |

diff --git a/docs/pages/references/bundler/endpoints/pimlico_simulateAssetChanges.mdx b/docs/pages/references/bundler/endpoints/pimlico_simulateAssetChanges.mdx
@@ -1,5 +1,7 @@
 # pimlico_simulateAssetChanges
 
+Returns the ERC-20, ERC-721, ERC-1155, and native token balance changes that would occur if a given user operation were executed on-chain — useful for previewing transfers and balance impact before submitting the user operation.
+
 :::warning
 NOTICE: This page is still in draft and the API may change.
 :::