From bcb22218628fbc938d468905c7921797a14ad47e Mon Sep 17 00:00:00 2001 From: avarobinson <45052879+avarobinson@users.noreply.github.com> Date: Tue, 10 Feb 2026 22:47:45 -0700 Subject: [PATCH 1/5] docs: add conditional sponsorship rules guide under sponsor gas (#1012). --- fern/docs.yml | 2 + .../conditional-sponsorship-rules.mdx | 120 ++++++++++++++++++ .../transactions/sponsor-gas/overview.mdx | 2 +- 3 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 533861685..fb69edf7e 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -1009,6 +1009,8 @@ navigation: contents: - page: Full sponsorship path: wallets/pages/transactions/sponsor-gas/index.mdx + - page: Conditional sponsorship rules + path: wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx - page: Solana sponsorship path: wallets/pages/transactions/solana/sponsor-gas-solana.mdx - page: Pay gas with any token diff --git a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx new file mode 100644 index 000000000..875db3908 --- /dev/null +++ b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx @@ -0,0 +1,120 @@ +--- +title: Conditional sponsorship rules +description: Control gas sponsorship with policy limits and custom webhook rules +slug: wallets/transactions/sponsor-gas/conditional-sponsorship-rules +--- + +Conditional sponsorship gives you precise control over **who** gets sponsored and **which transactions** you pay for. + +Use it to: + +* Protect your budget with hard spend caps +* Prioritize high-value users and actions +* Prevent abuse with allowlists, blocklists, and custom logic + +## Ways to configure sponsorship rules + +You can configure the same policy logic in two ways: + +1. **Dashboard**: Create or edit a Gas Manager policy in the [Alchemy dashboard](https://dashboard.alchemy.com/gas-manager/policy/create) +2. **Admin API**: Create or update policies programmatically with the [Gas Manager Admin API](/wallets/gas-manager-admin-api/gas-manager-admin-api-endpoints/gas-manager-admin-api-endpoints) + +Most teams start in the dashboard, then move to API-based management for automation. + +## Built-in policy limits + +Use built-in limits when you want fast setup without maintaining backend logic. + +You can combine these controls in one policy: + +* **Time-bounded policies**: Only sponsor during a specific start/end window +* **Per-user spend limits**: Cap sponsorship spend per wallet/user +* **Per-transaction spend limits**: Cap sponsorship per transaction +* **Global max spend**: Set a hard maximum spend for the full policy +* **Max transactions per user**: Limit number of sponsored transactions per user +* **Sender allowlist / blocklist**: Explicitly allow or deny sponsorship for selected senders + +These limits are ideal for growth campaigns, onboarding credits, and controlled rollouts. + +## Custom rules with webhooks + +For advanced use cases, add a webhook so your server can approve or reject sponsorship requests in real time. + +Examples: + +* Sponsor only swaps +* Sponsor only transactions that touch your contracts +* Sponsor only high-ROI users (for example, power users) +* Sponsor users with proof-of-humanity checks + +### How webhook-based sponsorship works + +When a sponsorship request is made, Gas Manager sends a `POST` request to your webhook. + +Your server evaluates the request and returns whether to approve sponsorship. + +#### Request payload + +```json +{ + "userOperation": {}, + "policyId": "", + "chainId": "", + "webhookData": "" +} +``` + +Payload fields: + +* `userOperation`: UserOperation payload (shape depends on EntryPoint version) +* `policyId`: Policy ID receiving the sponsorship request +* `chainId`: Chain ID for the request +* `webhookData` (optional): Additional app data, such as user attestations + +#### Expected webhook response + +Return HTTP `200` and: + +```json +{ + "approved": true +} +``` + +Set `approved` to: + +* `true` to sponsor gas +* `false` to reject sponsorship + +### Configure webhook rules on your policy + +In your policy's **Custom Rules** section, set: + +* `webhookUrl` (required): Endpoint Gas Manager calls for eligibility +* `approveOnFailure` (required, default `false`): If `true`, sponsorship is approved when webhook errors or times out + +In the Admin API, this configuration is represented as: + +```json +{ + "webhookRules": { + "webhookUrl": "https://your-server.com/sponsor-gas", + "approveOnFailure": false + } +} +``` + +## Recommended setup pattern + +For most teams, the best approach is: + +1. Start with built-in limits for immediate spend protection +2. Add webhook rules for business-specific checks +3. Decide your failure mode (`approveOnFailure`) based on risk tolerance: + * Prefer uptime: set to `true` + * Prefer strict control: set to `false` + +## Next steps + +* [Full sponsorship implementation](/wallets/transactions/sponsor-gas) +* [Gas Manager Admin API endpoints](/wallets/gas-manager-admin-api/gas-manager-admin-api-endpoints/gas-manager-admin-api-endpoints) diff --git a/fern/wallets/pages/transactions/sponsor-gas/overview.mdx b/fern/wallets/pages/transactions/sponsor-gas/overview.mdx index cf3b921cf..c5954256a 100644 --- a/fern/wallets/pages/transactions/sponsor-gas/overview.mdx +++ b/fern/wallets/pages/transactions/sponsor-gas/overview.mdx @@ -30,7 +30,7 @@ Get started [here](/wallets/transactions/sponsor-gas)! Set spending limits and rules to control costs From a782628461c8676cfa049c6fd301cd62d9337552 Mon Sep 17 00:00:00 2001 From: avarobinson <45052879+avarobinson@users.noreply.github.com> Date: Thu, 12 Feb 2026 11:20:00 -0800 Subject: [PATCH 2/5] docs: Update fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx --- .../transactions/sponsor-gas/conditional-sponsorship-rules.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx index 875db3908..137a8aa28 100644 --- a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx +++ b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx @@ -4,7 +4,7 @@ description: Control gas sponsorship with policy limits and custom webhook rules slug: wallets/transactions/sponsor-gas/conditional-sponsorship-rules --- -Conditional sponsorship gives you precise control over **who** gets sponsored and **which transactions** you pay for. +Conditional sponsorship gives you precise control over what transactions get sponsored. Use it to: From 7c46f4d49c11d9f245be845048c6b21395a5c142 Mon Sep 17 00:00:00 2001 From: avarobinson <45052879+avarobinson@users.noreply.github.com> Date: Thu, 12 Feb 2026 11:20:10 -0800 Subject: [PATCH 3/5] docs: Update fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx --- .../transactions/sponsor-gas/conditional-sponsorship-rules.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx index 137a8aa28..1c7e6188e 100644 --- a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx +++ b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx @@ -1,6 +1,6 @@ --- title: Conditional sponsorship rules -description: Control gas sponsorship with policy limits and custom webhook rules +description: Control gas sponsorship with spend limits and custom rules slug: wallets/transactions/sponsor-gas/conditional-sponsorship-rules --- From 564c29e1eda796493cd4e96f665e40acb199a0db Mon Sep 17 00:00:00 2001 From: avarobinson <45052879+avarobinson@users.noreply.github.com> Date: Thu, 12 Feb 2026 11:20:22 -0800 Subject: [PATCH 4/5] docs: Update fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx --- .../transactions/sponsor-gas/conditional-sponsorship-rules.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx index 1c7e6188e..de0e4ac0c 100644 --- a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx +++ b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx @@ -8,7 +8,7 @@ Conditional sponsorship gives you precise control over what transactions get spo Use it to: -* Protect your budget with hard spend caps +* Protect your budget with hard spending limit * Prioritize high-value users and actions * Prevent abuse with allowlists, blocklists, and custom logic From 8e1d15b3eab3709c9591f266addacb3362f10b84 Mon Sep 17 00:00:00 2001 From: avarobinson <45052879+avarobinson@users.noreply.github.com> Date: Thu, 12 Feb 2026 11:20:54 -0800 Subject: [PATCH 5/5] docs: Apply suggestions from code review --- .../sponsor-gas/conditional-sponsorship-rules.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx index de0e4ac0c..56261038f 100644 --- a/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx +++ b/fern/wallets/pages/transactions/sponsor-gas/conditional-sponsorship-rules.mdx @@ -17,7 +17,7 @@ Use it to: You can configure the same policy logic in two ways: 1. **Dashboard**: Create or edit a Gas Manager policy in the [Alchemy dashboard](https://dashboard.alchemy.com/gas-manager/policy/create) -2. **Admin API**: Create or update policies programmatically with the [Gas Manager Admin API](/wallets/gas-manager-admin-api/gas-manager-admin-api-endpoints/gas-manager-admin-api-endpoints) +2. **Admin API**: Create or update policies programmatically with the [Gas Manager Admin API](/wallets/api-reference/gas-manager-admin-api/gas-manager-admin-api-endpoints/gas-manager-admin-api-endpoints) Most teams start in the dashboard, then move to API-based management for automation. @@ -117,4 +117,4 @@ For most teams, the best approach is: ## Next steps * [Full sponsorship implementation](/wallets/transactions/sponsor-gas) -* [Gas Manager Admin API endpoints](/wallets/gas-manager-admin-api/gas-manager-admin-api-endpoints/gas-manager-admin-api-endpoints) +* [Gas Manager Admin API endpoints](/wallets/api-reference/gas-manager-admin-api/gas-manager-admin-api-endpoints/gas-manager-admin-api-endpoints)