> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ERC-4337 Paymaster: Gas Sponsorship Explained

> Learn how ERC-4337 paymasters work for gas sponsorship. Understand paymaster types, configuration, and how to implement gasless transactions in your dApp

# ERC-4337 Paymaster: Gas Sponsorship Explained

<Info>
  Biconomy provides all paymaster functionality through the **MEE (Modular Execution Environment)** stack. While this page explains how ERC-4337 paymasters work conceptually, you should use MEE to implement gas sponsorship in your applications—it provides paymaster capabilities plus cross-chain orchestration in a unified interface.
</Info>

<Accordion title="What is a Paymaster in ERC-4337?">
  A **Paymaster** is a smart contract in the ERC-4337 account abstraction standard that pays gas fees on behalf of users. Instead of users needing ETH for gas, the paymaster covers the cost.

  ```
  Traditional Transaction:
  User → pays gas in ETH → Transaction Executed

  With Paymaster:
  User → signs UserOperation → Paymaster pays gas → Transaction Executed
  ```

  Paymasters enable:

  * **Gasless transactions**: Users pay nothing
  * **Gas abstraction**: Users pay in ERC-20 tokens (USDC, DAI, etc.)
  * **Sponsored transactions**: Apps cover user gas costs
</Accordion>

<Accordion title="How does a Paymaster work technically?">
  The paymaster integrates with the ERC-4337 flow:

  ```
  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
  │    User     │───▶│   Bundler   │───▶│  EntryPoint │───▶│  Paymaster  │
  │  (signs     │    │  (submits   │    │  (validates │    │  (pays gas, │
  │   UserOp)   │    │   UserOp)   │    │   UserOp)   │    │   verifies) │
  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │   Account   │
                                        │  (executes  │
                                        │   action)   │
                                        └─────────────┘
  ```

  **Key steps:**

  1. User creates and signs a UserOperation
  2. UserOperation includes `paymasterAndData` field
  3. Bundler submits to EntryPoint
  4. EntryPoint calls `validatePaymasterUserOp` on Paymaster
  5. Paymaster validates and agrees to pay
  6. Transaction executes
  7. Paymaster's deposit is debited for gas
</Accordion>

<Accordion title="What types of Paymasters exist?">
  | Paymaster Type           | How It Works                               | Use Case                                 |
  | ------------------------ | ------------------------------------------ | ---------------------------------------- |
  | **Verifying Paymaster**  | Off-chain signature authorizes sponsorship | App-controlled sponsorship with policies |
  | **Token Paymaster**      | Accepts ERC-20 tokens as gas payment       | Let users pay gas in stablecoins         |
  | **Deposit Paymaster**    | Users pre-deposit funds for gas            | Enterprise/institutional use             |
  | **Sponsoring Paymaster** | Unconditionally sponsors gas               | Development, promotions                  |

  **Biconomy's MEE** provides all these paymaster capabilities:

  * Flexible sponsorship policies
  * Token payment options (pay gas in USDC, DAI, etc.)
  * Spending limits (per transaction, total)
  * Plus cross-chain gas abstraction (pay on any chain with tokens from any chain)
</Accordion>

<Accordion title="How do I implement gas sponsorship with Biconomy?">
  Biconomy provides paymaster functionality through MEE (Modular Execution Environment):

  **Step 1: Get your MEE API key from Dashboard**

  **Step 2: Initialize MEE client**

  ```typescript theme={null}
  import { createMeeClient, toMultichainNexusAccount } from "@biconomy/abstractjs";
  import { base } from "viem/chains";

  const account = await toMultichainNexusAccount({
    signer: userSigner,
    chains: [base]
  });

  const meeClient = await createMeeClient({ account });
  ```

  **Step 3: Send sponsored transaction**

  ```typescript theme={null}
  // Get quote with sponsored gas
  const quote = await meeClient.getQuote({
    instructions: [
      { calls: [{ to: contractAddress, data: encodedCall }] }
    ],
    feeToken: { address: "sponsored" }  // Gas sponsored via MEE
  });

  // Execute gasless transaction
  const { hash } = await meeClient.executeQuote({ quote });
  ```

  MEE handles all gas sponsorship automatically based on your dashboard configuration.
</Accordion>

<Accordion title="How do I configure sponsorship policies?">
  Configure policies in the Biconomy Dashboard or via API:

  **Per-Transaction Limit:**

  ```json theme={null}
  {
    "policy": {
      "transactionLimit": {
        "maxSpendUsd": 5
      }
    }
  }
  ```

  **Total Spending Limit:**

  ```json theme={null}
  {
    "policy": {
      "globalLimit": {
        "maxSpendUsd": 1000
      }
    }
  }
  ```
</Accordion>

<Accordion title="How do spending limits work?">
  Spending limits help you control costs and prevent abuse:

  **Per-Transaction Limits:**

  * Set maximum gas cost per individual transaction
  * Prevents unexpectedly expensive operations from draining your balance

  **Total Limits:**

  * Set an overall spending cap
  * MEE automatically stops sponsoring once the limit is reached

  Configure both limits in the Biconomy Dashboard for optimal cost control.
</Accordion>

<Accordion title="How do I let users pay gas in tokens?">
  MEE supports paying gas in ERC-20 tokens (gas abstraction):

  ```typescript theme={null}
  import { createMeeClient, toMultichainNexusAccount } from "@biconomy/abstractjs";
  import { base } from "viem/chains";

  const account = await toMultichainNexusAccount({
    signer: userSigner,
    chains: [base]
  });

  const meeClient = await createMeeClient({ account });

  // Get quote with token payment
  const quote = await meeClient.getQuote({
    instructions: [
      { calls: [{ to: contractAddress, data: calldata }] }
    ],
    // User pays gas in USDC instead of ETH
    feeToken: {
      address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      chainId: base.id
    }
  });

  const { hash } = await meeClient.executeQuote({ quote });
  ```

  **MEE supports cross-chain gas payment** - pay for gas on any chain using tokens from any other supported chain!

  **Supported gas payment tokens** vary by chain. Common options:

  * USDC
  * USDT
  * DAI
  * WETH

  Check [supported gas tokens](/new/getting-started/supported-gas-tokens) for the full list.
</Accordion>

<Accordion title="How do I monitor gas sponsorship usage?">
  Biconomy Dashboard provides:

  * Real-time gas spending
  * Contract interaction breakdown
  * Spending trends over time

  **API Access:**

  ```typescript theme={null}
  // Get usage statistics
  const stats = await fetch(
    "https://api.biconomy.io/v1/mee/stats",
    {
      headers: { "x-api-key": API_KEY }
    }
  ).then(r => r.json());

  console.log(stats);
  // {
  //   totalTransactions: 15420,
  //   totalGasSponsored: "1.234",  // ETH
  //   uniqueUsers: 3250,
  //   topContracts: [...],
  //   dailyTrend: [...]
  // }
  ```

  **Set up alerts:**

  ```typescript theme={null}
  // Configure spending alerts in dashboard
  const alertConfig = {
    dailySpendThreshold: "$50",
    unusualActivityThreshold: "200%",
    lowBalanceThreshold: "0.01 ETH",
    notificationChannels: ["email", "slack"]
  };
  ```
</Accordion>

<Accordion title="What are gas sponsorship security best practices?">
  **1. Set per-transaction limits:**

  ```json theme={null}
  {
    "policy": {
      "spendingCaps": {
        "perTransaction": "$5"
      }
    }
  }
  ```

  **2. Set total spending caps:**

  ```json theme={null}
  {
    "policy": {
      "spendingCaps": {
        "total": "$1000"
      }
    }
  }
  ```

  **3. Monitor for abuse:**

  * Watch for unusual patterns
  * Set up anomaly alerts
  * Review spending regularly in the dashboard
</Accordion>

<Accordion title="How does MEE handle sponsorship failures?">
  Common failure scenarios and handling:

  | Scenario                           | Cause                          | Solution                    |
  | ---------------------------------- | ------------------------------ | --------------------------- |
  | "Sponsorship validation failed"    | Policy rejected                | Check spending limits       |
  | "Insufficient sponsorship balance" | Low balance                    | Top up deposit in dashboard |
  | "Spending limit exceeded"          | Transaction or total limit hit | Adjust limits in dashboard  |
  | "Quote expired"                    | Quote too old                  | Get fresh quote             |

  **Implement fallback logic:**

  ```typescript theme={null}
  async function sendWithFallback(instructions) {
    try {
      // Try sponsored first
      const quote = await meeClient.getQuote({
        instructions,
        feeToken: { address: "sponsored" }
      });
      return await meeClient.executeQuote({ quote });
    } catch (error) {
      if (error.message.includes("sponsorship")) {
        // Fall back to user-paid gas (in tokens)
        console.log("Sponsorship unavailable, user pays gas in USDC");
        const quote = await meeClient.getQuote({
          instructions,
          feeToken: { address: USDC_ADDRESS, chainId: base.id }
        });
        return await meeClient.executeQuote({ quote });
      }
      throw error;
    }
  }
  ```
</Accordion>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Build Gasless App" icon="code" href="/faq/build-gasless-web3-app">
    Complete integration guide
  </Card>

  <Card title="Gasless Transactions" icon="gas-pump" href="/faq/gasless-transactions-evm">
    How gasless transactions work
  </Card>
</CardGroup>