# Ethereum Paymaster — Gas Sponsorship

The Openfort Ethereum Paymaster enables gas sponsorship for your users' transactions on EVM-compatible chains. With gas sponsorship powered by the ERC-4337 Paymaster standard, you can deliver sponsored transactions where users don't need to hold native tokens to interact with your application.

## Overview

The Ethereum Paymaster provides gas sponsorship by:

1. Receiving a UserOperation from your application
2. Validating it against your gas sponsorship rules
3. Signing the operation with the paymaster's key
4. Returning the signature for inclusion in the sponsored transaction

When the sponsored UserOperation is executed on-chain, the paymaster contract verifies the signature and covers the gas fees on behalf of the user.

:::tip
The paymaster signature is valid for **10 minutes**. Submit your sponsored UserOperation to the blockchain within this window, as unused gas allocations are released after expiration.
:::

## Getting Started

To use the Paymaster, make JSON-RPC requests to:

```text
https://api.openfort.io/rpc/{chainId}
```

Replace `{chainId}` with the appropriate chain ID. Include your Openfort publishable key in the `Authorization` header:

```http
Authorization: Bearer YOUR_OPENFORT_PUBLISHABLE_KEY
```

Get your public key from the [Openfort Dashboard](https://dashboard.openfort.io).

## Available Endpoints

| Method | Description |
|--------|-------------|
| [`pm_sponsorUserOperation`](/docs/products/infrastructure/paymaster/ethereum/endpoints#pm_sponsoruseroperation) | Sponsor a UserOperation |
| [`pm_validateSponsorshipPolicies`](/docs/products/infrastructure/paymaster/ethereum/endpoints#pm_validatesponsorshippolicies) | Validate against sponsorship policies |
| [`pm_supportedEntryPoints`](/docs/products/infrastructure/paymaster/ethereum/endpoints#pm_supportedentrypoints) | List supported EntryPoints |

## Quick Example

This example shows how to use the Openfort Paymaster with viem's `createPaymasterClient`:

```typescript
import { createPublicClient, http } from 'viem'
import { sepolia } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'
import {
  createBundlerClient,
  createPaymasterClient,
  toCoinbaseSmartAccount
} from 'viem/account-abstraction'

// Create a public client for reading blockchain state
const client = createPublicClient({
  chain: sepolia,
  transport: http(),
})

// Create the paymaster client with Openfort
const paymasterClient = createPaymasterClient({
  transport: http('https://api.openfort.io/rpc/11155111', {
    fetchOptions: {
      headers: {
        'Authorization': 'Bearer YOUR_OPENFORT_PUBLISHABLE_KEY',
      },
    },
  }),
})

// Create a smart account (using Coinbase Smart Account as an example)
const owner = privateKeyToAccount(process.env.PRIVATE_KEY)
const account = await toCoinbaseSmartAccount({
  client,
  owners: [owner],
  version: '1.1',
})

// Create a bundler client that uses the paymaster for gas sponsorship
const bundlerClient = createBundlerClient({
  account,
  paymaster: paymasterClient,
  client,
  paymasterContext: {
    policyId: 'YOUR_POLICY_ID_HERE'
  },
  transport: http('https://api.openfort.io/rpc/11155111', {
    fetchOptions: {
      headers: {
        'Authorization': 'Bearer YOUR_OPENFORT_PUBLISHABLE_KEY',
      },
    },
  }),
})

// Send a sponsored UserOperation
const hash = await bundlerClient.sendUserOperation({
  calls: [{
    to: '0xcb98643b8786950F0461f3B0edf99D88F274574D',
    value: 0n,
    data: '0x1234',
  }],
})

const receipt = await bundlerClient.waitForUserOperationReceipt({ hash })
console.log('UserOperationReceipt:', receipt)
```

The `paymasterContext` object accepts `policyId` to specify which [gas sponsorship policy](/docs/configuration/gas-sponsorship) to use.

## gas sponsorship Policies

To use the Ethereum Paymaster, you must define a **gas sponsorship policy** that controls when transactions receive gas sponsorship. Create policies in the [Openfort Dashboard](https://dashboard.openfort.io) or via the [Policy Engine](/docs/configuration/policies).

### Policy scopes

Ethereum gas sponsorship supports two policy scopes:

* **`project` scope** — Applies automatically to all transactions. The system discovers matching project-scoped policies in priority order. No `policyId` is needed in the request.
* **`transaction` scope** — Applies only when the `policyId` is explicitly passed in `paymasterContext`. Uses strict validation — if the policy's rules don't match, the transaction is rejected.

:::tip
Use **project** scope for broad sponsorship rules (e.g., sponsor all transactions under 1 ETH). Use **transaction** scope when you need explicit control over which policy applies to each request.
:::

Learn more about configuring [policies](/docs/configuration/policies) and [policy rules](/docs/configuration/policies/rules-reference).

## Validity Window

Sponsored transactions have a **10-minute validity window** during which they must be submitted to the blockchain. After this window expires, unused gas sponsorship allocations are released.

This time limit prevents potential abuse scenarios where accumulated sponsored UserOperations could drain the paymaster's gas sponsorship funds.

## Next Steps

* [Endpoint Reference](/docs/products/infrastructure/paymaster/ethereum/endpoints) - Detailed documentation for all paymaster methods
* [Error Reference](/docs/products/infrastructure/paymaster/ethereum/errors) - Common errors and how to resolve them
* [Policy Engine](/docs/configuration/policies) - Configure rules and conditions for gas sponsorship
* [Gas Sponsorship Overview](/docs/configuration/gas-sponsorship) - Learn more about gas sponsorship and gas sponsorship features