Skip to content

How to use Sponsorship Policies

What are Sponsorship Policies?

Sponsorship Policies are hosted policies that allow you to define custom rules for sponsorships.

You can put limits to the global amount of sponsorships, the amount of sponsorships per user, and per user operation.

Start by going to the sponsorship policies page on the Pimlico dashboard and clicking on the "Create Policy" button.

Usage of Sponsorship Policies with permisionless.js

If you are using permissionless.js, you can use the PimlicoPaymasterClient to use sponsorship policies.

Create the clients

First we must create the public, bundler, and (optionally) paymaster clients that will be used to interact with the SimpleAccount.

import { createPublicClient, http } from "viem"
import {
	createPimlicoBundlerClient,
	createPimlicoPaymasterClient,
} from "permissionless/clients/pimlico"
import { ENTRYPOINT_ADDRESS_V07 } from "permissionless"
 
const publicClient = createPublicClient({
	transport: http("https://rpc.ankr.com/eth_sepolia"),
})
 
const bundlerClient = createPimlicoBundlerClient({
	transport: http("https://api.pimlico.io/v2/sepolia/rpc?apikey=YOUR_PIMLICO_API_KEY"),
	entryPoint: ENTRYPOINT_ADDRESS_V07,
})
 
const pimlicoPaymasterClient = createPimlicoPaymasterClient({
	transport: http("https://api.pimlico.io/v2/sepolia/rpc?apikey=YOUR_PIMLICO_API_KEY"),
	entryPoint: ENTRYPOINT_ADDRESS_V07,
})

Create an account

Now, create an account. This can any of the accounts supported by permissionless.js or custom accounts conforming to the interface. For this example, we'll use a Simple account.

import { privateKeyToSimpleSmartAccount } from "permissionless/accounts"
 
export const simpleSmartAccount = await privateKeyToSimpleSmartAccount(publicClient, {
	privateKey: "0xPRIVATE_KEY",
	entryPoint: ENTRYPOINT_ADDRESS_V07,
})

Create the smart account client with middleware

When creating the smartAccountClient, we can pass in a middleware.sponsorUserOperation function that will be called before a user operation is signed and sent. This is where we can pass in the sponsorshipPolicyId that we want to use.

import { sepolia } from "viem/chains"
import { createSmartAccountClient } from "permissionless"
 
export const smartAccountClient = createSmartAccountClient({
	account: simpleSmartAccount,
	entryPoint: ENTRYPOINT_ADDRESS_V07,
	chain: sepolia, // or whatever chain you are using
	bundlerTransport: http("https://api.pimlico.io/v2/sepolia/rpc?apikey=YOUR_PIMLICO_API_KEY"),
	middleware: {
		gasPrice: async () => {
			return (await bundlerClient.getUserOperationGasPrice()).fast // if using pimlico bundlers
		},
		sponsorUserOperation: async (args) => {
			return pimlicoPaymasterClient.sponsorUserOperation({
				...args,
				sponsorshipPolicyId: "sp_my_policy_id",
			})
		},
	},
})

Usage of Sponsorship Policies API

After creating a policy, you can take its ID and use it by passing it into the pm_sponsorUserOperation method. If the user operation does not meet the requirements of the policy, the method will return an error.

{
    "jsonrpc": "2.0",
    "method": "pm_sponsorUserOperation",
    "params": [
        {
            "sender": "0x1234567890123456789012345678901234567890",
            "nonce": "0x1",
            "initCode": "0x",
            "callData": "0x",
            "callGasLimit": "0x100000",
            "verificationGasLimit": "0x20000",
            "preVerificationGas": "0x10000",
            "maxFeePerGas": "0x3b9aca00",
            "maxPriorityFeePerGas": "0x3b9aca00",
            "paymasterAndData": "0x",
            "signature": "0x"
        },
        "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
        {
            "sponsorshipPolicyId": "sp_amused_gladiator"
        }
    ],
    "id": 1
}