Integrating Base Paymaster for Gasless Transactions in a Wagmi Project

This comprehensive guide walks you through the process of adding Base Paymaster support to enable gasless transactions in your Wagmi project. By leveraging Coinbase Developer Platform (CDP) tools and Wagmi’s experimental hooks, you can streamline onchain interactions while reducing user friction.

Prerequisites

Before proceeding, ensure you have:

• A Wagmi project set up (Viem or Ethers.js configuration).
• A Coinbase Developer Platform (CDP) account (sign up here).
• Basic familiarity with smart contract interactions and RPC endpoints.

👉 Explore advanced Wagmi configurations

Step 1: Configure CDP Account and Paymaster

1.1 Access Paymaster Services

1. Log in to your CDP dashboard.
2. Navigate to Onchain Tools > Paymaster and select the Configuration tab.
3. Choose your target chain (Base or Base Sepolia) and copy the Paymaster & Bundler endpoint (RPC URL).

Key Action:

• Store the endpoint in your .env file:

  NEXT_PUBLIC_CDP_PAYMASTER=your_paymaster_rpc_url

1.2 Whitelist Contracts

In the Contract allowlist section:

1. Add the contract addresses for gasless transactions.
2. Specify function names (e.g., mintTo) and assign descriptive labels.
3. Click Add to save each entry.

Step 2: Configure Wagmi for Base

Update wagmi.ts to support Base network, WalletConnect, and Coinbase Wallet connectors:

import { http, cookieStorage, createConfig, createStorage } from 'wagmi';
import { base } from 'wagmi/chains';
import { coinbaseWallet, injected, walletConnect } from 'wagmi/connectors';

export function getConfig() {
  return createConfig({
    chains: [base],
    connectors: [
      injected(),
      coinbaseWallet(),
      walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID }),
    ],
    storage: createStorage({
      storage: cookieStorage,
    }),
    ssr: true,
    transports: {
      [base.id]: http(),
    },
  });
}

declare module 'wagmi' {
  interface Register {
    config: ReturnType<typeof getConfig>;
  }
}

Key Notes:

• Replace NEXT_PUBLIC_WC_PROJECT_ID with your WalletConnect project ID.
• For production, consider using a proxy service to secure paymaster endpoints.

👉 Optimize your Wagmi setup

Step 3: Implement Wagmi Hooks for Gasless Transactions

Use Wagmi’s experimental hooks to handle:

• Wallet connection (useAccount, useConnect).
• Paymaster capabilities (useCapabilities).
• Onchain actions (useWriteContracts).

Example: Minting an NFT with Gasless Support

'use client';
import { useAccount, useConnect, useDisconnect } from 'wagmi';
import { useState, useMemo } from 'react';
import { coinbaseWallet } from 'wagmi/connectors';
import { abi, contractAddress } from '../utils';
import { useCapabilities, useWriteContracts } from 'wagmi/experimental';

export default function MintPage() {
  const { address, isConnected } = useAccount();
  const { connect } = useConnect();
  const { disconnect } = useDisconnect();
  const [isMinting, setIsMinting] = useState(false);

  const { writeContracts } = useWriteContracts({
    mutation: { onSuccess: () => console.log('Mint successful') },
  });

  // Check paymaster capabilities
  const { data: availableCapabilities } = useCapabilities({
    account: address,
  });

  const capabilities = useMemo(() => {
    if (!availableCapabilities || !address) return {};
    const capabilitiesForChain = availableCapabilities[address.chainId];
    if (
      capabilitiesForChain['paymasterService'] &&
      capabilitiesForChain['paymasterService'].supported
    ) {
      return {
        paymasterService: {
          url: process.env.NEXT_PUBLIC_CDP_PAYMASTER, // Use proxy in production
        },
      };
    }
    return {};
  }, [availableCapabilities, address]);

  const handleMint = async () => {
    setIsMinting(true);
    try {
      writeContracts({
        contracts: [
          {
            address: contractAddress,
            abi,
            functionName: 'mintTo',
            args: [address],
          },
        ],
        capabilities,
      });
    } catch (error) {
      console.error('Minting failed:', error);
    } finally {
      setIsMinting(false);
    }
  };

  return (
    <div>
      <p>{isConnected ? `Connected wallet: ${address}` : 'No wallet connected'}</p>
      <button
        onClick={() => connect({ connector: coinbaseWallet() })}
      >
        {isMinting ? 'Minting...' : isConnected ? 'Mint NFT' : 'Connect Wallet'}
      </button>
      {isConnected && <button onClick={() => disconnect()}>Disconnect</button>}
    </div>
  );
}

Critical Components:

1. useCapabilities: Detects if the wallet supports paymasterService.
2. useWriteContracts: Executes gasless transactions using configured capabilities.

Troubleshooting

For advanced debugging, consult the CDP troubleshooting guide.

FAQs

Q1: Can I use Base Paymaster with MetaMask?

A: Yes, but MetaMask must support ERC-4337 Account Abstraction. Use wallets like Coinbase Wallet for guaranteed compatibility.

Q2: How are gas fees sponsored?

A: The Base Paymaster covers gas costs for whitelisted contracts. Configure your CDP account to set spending limits.

Q3: Is this suitable for production apps?

A: Yes, but always use a proxy service to hide paymaster endpoints and manage rate limits.

Conclusion

By integrating Base Paymaster, you enable seamless, gasless transactions in Wagmi projects. Follow best practices for security, such as contract whitelisting and endpoint proxying, to ensure scalability.