Docs

Sponsorship rules

You can easily define rules around which transactions (User Ops) the paymaster should sponsor. This can be used to prevent abuse, progressively onboard users, and incentivize specific in-app actions.

You can set the following sponsorship rules

  • Global spend limits: Maximum gas cost (in USD) that you want to sponsor. This applies for the duration of the billing period (monthly).
  • Contract address restrictions: Use this if you want to sponsor transactions sent only to a specific set of contracts. Transactions sent to contracts outside this allowlist will remain unsponsored.
  • Chain restrictions: Use this if you want to sponsor transactions only on certain chains. If this is not set, transactions on all supported chains will be sponsored.
  • Server verifier: This is a general purpose check that can be used to define custom rules. Before a transaction is sent, it checks with an endpoint that you specify on whether it should be sponsored or not.

We highly recommended that you set sponsorship rules before your app goes live to prevent malicious actors from abusing your paymaster, which could lead to unexpectedly large bills.

Setting Sponsorship rules

You can easily set sponsorship rules by going to the configuration tab in the Smart Wallet dashboard..To use them in your app all you need to do is pass your API key, sponsorship rules will automatically be applied.

Setting up a server verifier

You can set up a server verifier by providing a URL that the paymaster will call before sponsoring a transaction. This allows for fine grained control over which transactions are sponsored.

The thirdweb infrastructure will send a POST request to the URL you specify with the following JSON payload:

// thirdweb will call your server with the following JSON body as a POST request
{
	clientId: string; // the clientId that is making the request
	chainId: number; // the chainId of the transaction
	userOp: {
		sender: string; // the address of the sender
  		targets: string[]; // the addresses of the target contracts or wallets
  		gasLimit: string; // the gas limit of the transaction
  		gasPrice: string; // the gas price of the transaction in wei
	};
}

Your server should respond with a 200 and the following JSON payload:

// you should respond with the following JSON payload
{
	isAllowed: boolean; // whether the transaction should be sponsored or not
	reason: string?; // optional reason for why the transaction is not allowed
}

Note: for performance reasons, your server should respond within 5 seconds. If it takes longer, the transaction will be unsponsored.

FAQs

What happens if a limit is hit? Does the transaction fail or does it go unsponsored?

If a limit is hit the transaction will go unsponsored. If you are spinning up fresh accounts for users in your app, it is unlikely the the user accounts will hold any funds. You can catch the following out of funds error to gracefully handle this within your app AA21 didn't pay prefund.

What networks are sponsorship rules available in?

Sponsorship rules apply across all the networks that we support smart wallets in. You don't need to specify different rules for each network or each account factory as long as they use the same client ID. However, you can restrict sponsored transactions to specific networks if you choose to.

Will sponsorship rules work with third-party paymasters?

No, sponsorship rules will apply on if you are using thirdweb's paymaster.

Pricing

Setting a server verifier requires your account to be on the growth plan. The other policies are free to use. There is no usage based pricing for policies.