docs(features): add Gas Top-Up intro

[scout-relayprotocol]

Implements MAR-1414: Gas Top-Up feature page intro

What this changes

• Adds the approved payout-focused marketing intro to features/gas-top-up.mdx.
• Covers how Gas Top-Up works, why it matters, target audiences, and current limitations.
• Preserves the existing enablement and support-checking guidance below the new intro.
• Links related Gasless Execution, Price Stabilization, and Supported Tokens & Routes docs.

How I verified

• git diff --check
• Confirmed all added internal link targets and the fixed-rates anchor exist.
• Manually reviewed the final MDX against the repository style guide and approved Notion copy.
• No package scripts are defined in this docs repository; GitHub handles PR-time review.

Open questions

• None. The existing technical sections remain intentionally unchanged in scope, aside from parameter emphasis matching the style guide.

---

🤖 Opened by Scout (autonomous). Ready for human review.
Linear: https://linear.app/relayprotocol/issue/MAR-1414/gas-top-up-feature-page-intro

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
unevenlabs	🟢 Ready	View Preview	Jul 31, 2026, 11:05 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Greptile Summary

This documentation update expands the Gas Top-Up page with payout-focused guidance, configuration steps, intended use cases, limitations, and related-feature links. The documented behavior was checked against the live Relay API: a quote using topupGas: true without topupGasAmount succeeded and included native destination-chain ETH gas. The local documentation links and retained route-support guidance also resolved successfully.

The change is safe to merge.

Confidence Score: 5/5

The updated guidance accurately describes the verified Gas Top-Up quote behavior and does not introduce executable application code.

The central product claim was exercised with a live quote request, the API contract was checked, and the updated page links and support guidance were validated without identifying a defect.

Files Needing Attention: None.

T-Rex Logs

What T-Rex did

• I ran the gas-top-up contract validation script from /home/user/repo and confirmed the run exited successfully, while validating local MDX links and the live Relay OpenAPI, Chains, and Quote endpoints.
• The top-up quote endpoint returned HTTP 200 for a Base USDC to Optimism USDC quote with topupGas: true and no topupGasAmount.
• The validation output showed details.currencyGasTopup for ETH on chain 10 with amountUsd 2.000000, confirming the page documents the optional amount and destination-native gas behavior.
• No further validation tasks remain; if more coverage is desired, a funded end-to-end settlement could be run to inspect the recipient's post-fill native balance.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into scout/MAR-1414-..." | Re-trigger Greptile}

[github-actions]

Claude finished @pedromcunha's task in 1m 58s —— View job

---

Code Review: Gas Top-Up feature page intro

• Gather context (diff, full page, style guide)
• Verify internal links and anchors resolve
• Check against AGENTS.md style guide (§2, §3.1)
• Post review

Links check: all clean. /features/gasless-execution, /references/api/api_resources/supported-routes, and /features/price-stabilization#fixed-rates all resolve (### Fixed Rates exists at features/price-stabilization.mdx:654, slug matches). No broken targets, no relative or absolute-URL links, docs.json already lists the page. This is a docs-only MDX change; there are no build/lint/test scripts in the repo, so I verified by reading rather than running anything.

The copy itself is strong and the technical claims are accurate. My findings are about duplication and fit with the style guide.

---

1. The new sections duplicate the existing ones (blocking, in my view)

The page now states the same two facts twice, in two different registers:

New	Pre-existing
gas-top-up.mdx:20 — "Set topupGas to true on the quote, and optionally set the amount with topupGasAmount"	gas-top-up.mdx:57-60 — ## Enabling Gas Top-Up, same two bullets
gas-top-up.mdx:49 — "EVM chains only. Not available when bridging the destination chain's native token itself… must support bridging; check [Supported Tokens & Routes]"	gas-top-up.mdx:62-72 — ## Checking Gas Top-Up Support, the same three conditions with the same link

Two copies of the same facts on one page will drift the first time behavior changes, and a reader who scrolls past the --- reads the same thing again in a different voice. I'd fold the ## How it works step 1 into the intro prose (it already says "set one flag on the quote" at line 14) and either delete ## Limitations or delete ## Checking Gas Top-Up Support — not keep both. Fix this →

2. Lines 6 and 8 re-render the title and description

Mintlify renders frontmatter title as the H1 and description as the subtitle beneath it. So the top of the page becomes:

Gas Top-Up
Include destination-chain native gas in bridged fills so recipients can transact immediately.
Gas Top-Up: payouts that land usable.
Include destination gas with any fill. One parameter.

Both bold lines restate what's already rendered above them. Worth checking on the preview deployment — I'd cut both and let the intro paragraph at line 10 lead. Fix this →

3. Style guide deviations (AGENTS.md)

• §3.1 requires a definitional intro. Feature guides must open with "one paragraph, starts with <FeatureName> is a feature that … or similar definitional framing." The removed sentence did exactly that; the replacement opens with a problem narrative and doesn't define Gas Top-Up until line 14. Compare the exemplar features/fast-fill.mdx:8. Every other page in features/ opens definitionally — no page currently uses bold headline lines.
• §2.9 restricts bold to "parameter names, values the reader has to type/recognize, and UI element names." Lines 6/8 and the bolded lead-ins throughout ## Why it matters / ## Who it's for are the use-case guide benefits-block pattern (§3.2), not the feature-guide pattern.
• §2.4 assigns tone by page type: features/ is "practical and task-oriented"; "positioning-first, marketing-adjacent" is the use-cases/ profile. ## Who it's for (PSPs, Wallets, Onchain Apps, Chains & RaaS) is segment positioning — reasonable content for Relay to publish, but §3.2 suggests it lives in use-cases/. Flagging as a judgment call for the human reviewer rather than something I'd change unilaterally.
• §3.1 section names: the profile's optional sections are ## Requirements, ## How to use it?, ## Caveats. ## How it works / ## Limitations are near-synonyms of two of those under different names. The pre-existing ## Enabling… / ## Checking… headings already deviated, so the page now has four headings and no two follow the profile.

4. Nits

• gas-top-up.mdx:16 — comma splice: "…removes the gas requirement where a transaction starts, gas top-up equips the recipient…". Use a semicolon or "while". Same line opens with "It's the destination-side half…", where §2.3 asks for a named subject over generic "it".
• Inconsistent casing of the feature name across the page: "Gas Top-Up" (6), "gas top-up" (14, 16, 51, 57), "Top-up" (43). §5 doesn't fix a form for this term, but one page should pick one. The pre-existing prose used lowercase gas top-up.
• gas-top-up.mdx:30 — bold closes on a comma mid-sentence ("Kill the "now go buy ETH" moment, and the support tickets…"), unlike the sibling bullets which bold a complete lead-in.
• gas-top-up.mdx:45 — RaaS is never expanded on first use.
• gas-top-up.mdx:20-23 — a numbered list reads as reader instructions, but steps 2–4 describe system behavior, not actions the reader takes (§2.3 reserves imperative phrasing for step-by-step instructions).
• The page claims "one parameter" four times but never shows a code block. §3.1 suggests ### Example with a <CodeGroup> (SDK + API) — out of scope for this PR, but it's the thing that would most help an integrator here.

Parameter emphasis change to lines 59-60 is correct — **topupGas** matches §2.9's prose convention. Good catch in the original PR.
· Branch: scout/MAR-1414-gas-top-up-feature-page-intro