docs(fast-fill): add product introduction

[scout-relayprotocol]

Implements MAR-1415: Fast Fill feature page intro

What this changes

• Adds the approved Fast Fill positioning and explanation to features/fast-fill.mdx
• Covers the customer value, flow, target integrators, and enterprise scope
• Preserves the existing requirements, code examples, app-balance guidance, and caveats

How I verified

• git diff --check
• Parsed docs.json with python3 -m json.tool
• Verified every new root-relative documentation link resolves to an existing page
• Reviewed the final MDX diff against the repository style guide

Open questions

• None. The internal follow-ups about historical adoption, numeric speed claims, and deposit-address eligibility are intentionally not included in the public copy.

---

🤖 Opened by Scout (autonomous). Ready for human review.
Linear: https://linear.app/relayprotocol/issue/MAR-1415/fast-fill-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:06 AM

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

[github-actions]

Claude finished @pedromcunha's task in 2m 6s —— View job

---

Code review — PR #393

• Gather context (diff, style guide, peer feature pages)
• Verify links resolve (/features/price-stabilization, /features/fee-sponsorship both exist ✅)
• Check against AGENTS.md style guide
• Post review

The prose is strong and the structure is clean. Three findings below are factual conflicts with the rest of the same page and should be fixed before merge; the remainder are style-guide and consistency notes.

---

🔴 1. maxFillAmountUsd is described as a cap on the variance you absorb — it isn't

features/fast-fill.mdx:16 and features/fast-fill.mdx:35:

…absorbs any movement in fees or gas while it does, capped at an amount you set and released automatically…
You absorb the variance, capped. Fees and gas can move between completion and settlement; your balance covers it, up to a USD cap you set…

But line 252 on the same page defines the parameter as an eligibility threshold, not an exposure cap:

You can use the maxFillAmountUsd parameter to set a maximum USD value for a fast fill request. If the request's value exceeds this limit, the fast fill will not be executed.

And features/fast-fill.mdx:263 confirms the variance itself is uncapped: "Slippage may lead to a surplus or shortage in your app balance." An integrator reading the intro would believe their fee/gas downside is bounded by maxFillAmountUsd. It isn't — the cap only decides whether a given fill happens at all. Note line 27 ("Set a USD cap per transaction; anything above it simply isn't accelerated") states this correctly, so the page contradicts itself.

Fix this →

---

🔴 2. Positioning omits the actual downside: an origin deposit that never lands

The intro presents settlement as unconditional — :16 "released automatically once the payment settles", :25 "When the incoming payment confirms, the hold releases automatically."

features/fast-fill.mdx:73-75 says otherwise:

If the deposit never lands, Relay does not release the hold. The sponsoring app bears the loss, and the held amount becomes a permanent debit against its app balance.

This is the single most important thing an integrator needs to know before enabling the feature, and the "Why it matters → For integrators" section reduces the risk story to "Fees and gas can move." Suggest adding one honest line to ## How it works step 4 or to the third integrator bullet — the risk is a fair trade, not something to hide.

Fix this →

---

🟡 3. "Instant, unconditionally" / "Instant, every time" are contradicted 20 lines later

:33 Instant, unconditionally. and :39 Instant, every time. — but :27 says "anything above it simply isn't accelerated" and :51 gates the feature behind an API key, a linked wallet, and a funded balance. "Unconditionally" is the one word on the page that a reader can catch as false. Something like "Instant on the flows you choose" keeps the punch without the overclaim.

---

🟡 4. The §3.1-required definitional intro was removed

AGENTS.md §3.1 lists exactly two required elements for features/*.mdx: frontmatter, and an intro paragraph that "starts with <FeatureName> is a feature that … or similar definitional framing."

The diff deletes that sentence and opens with a bold tagline (:8) instead. Every peer page keeps the definitional opener — price-stabilization.mdx:6 ("Price Stabilization gives you two mechanisms…"), gas-top-up.mdx:6 ("Gas top-up automatically includes…"). Restoring a one-sentence definition as the first line (tagline second, or folded in) would satisfy the guide without losing the new voice.

Fix this →

---

🟡 5. ## Scope duplicates ## Requirements, with a naming mismatch

:51 — "it requires an API key, a linked funding address, and a funded app balance" — is immediately followed by :57-63, which lists those same three items in more detail. The redundancy is avoidable, and "a linked funding address" names the same thing that :62 calls "A Fee Sponsorship Wallet". Pick one name (the existing one), or drop the enumeration from Scope and let it link down to Requirements.

Also worth confirming with product: "Fast Fill is an enterprise feature" is a new claim. Nothing else in the docs gates it that way, and Requirements describes a self-serve dashboard flow (create an API key, link a wallet by signing a message). If "enterprise" means a sales conversation is required, Requirements should say so too; if it just means "needs an API key and balance," the word overstates it.

---

🔵 Minor / style

• :51 first-mention link. §2.6 asks for a link on first mention — "API key" is unlinked here but linked at :61. Same for "app balance," first mentioned at :16.
• :12 em-dash spacing. variable—the sending chain's confirmation time—is uses unspaced em dashes; the repo (and AGENTS.md itself) uses spaced —.
• :12 concrete numbers. §2.4 asks for concrete numbers when available. "settle in seconds" and "some confirm in about a second, others take minutes" would land harder with the real median.
• Tone drift toward §3.2. ## Why it matters and ## Who it's for are positioning-first, marketing-adjacent content — the §3.2 use-case-guide register — inside a §3.1 feature guide ("practical, task-oriented"). Not wrong on its own, but this page is now roughly half positioning before the reader reaches Requirements. Worth a deliberate call on whether the segment-by-segment pitch belongs here or on a use-cases/ page that links in.
• :10 "your users get instant" reads as a dropped noun. Fine if intentional as voice.

---

Verified: both new links resolve to existing pages, docs.json needs no change (page already in nav), diff is whitespace-clean, and the existing requirements / examples / caveats are preserved as the PR description claims.

No changes were made — this is review feedback only, per the review request.
· scout/MAR-1415-fast-fill-feature-page-intro

[greptile-apps]

Greptile Summary

This documentation update adds a product introduction, transaction lifecycle, enterprise prerequisites, and related-feature guidance for Fast Fill. Two product claims need correction: Fast Fill applies to eligible Relay requests identified by a Relay request ID, rather than arbitrary onchain transactions; and Fee Sponsorship does not itself guarantee a 1:1 output amount. The documented Relay request flow and Price Stabilization conditions confirm both issues.

Merge safety: not ready until the eligibility wording and fixed-rate requirements are accurately described.

Confidence Score: 3/5

The page needs two accuracy corrections before it safely communicates Fast Fill integration requirements and pricing behavior.

The Relay request-ID requirement and the distinction between fee sponsorship and fixed-rate pricing were both confirmed through focused documentation-contract validation.

Files Needing Attention: features/fast-fill.mdx requires updates at lines 16 and 53.

T-Rex Logs

What T-Rex did

• T-Rex produced a proof for the posted P1 finding on Fast Fill eligibility, including the focused Fast Fill validation source, the related documentation sentence, and the Safe API probe validation.
• T-Rex produced a proof for the posted P1 finding about the 1:1 claim, including the focused validator source, the captured validator source, and the fee-sponsored-only and fixed-rate validation outputs.
• T-Rex produced a proof for another P1 finding, with no artifacts attached.
• T-Rex produced a general-contract-validation-proof detailing the exact recommended final comment guidance and notes about the live failure-path probe requiring credentials.
• T-Rex produced a general-contract-validation-proof describing the Fee Sponsorship versus fixed-rate distinction and pointing to the specific validation script and captured outputs.

_{Ran code and verified through T-Rex}

Comments Outside Diff (2)

1. General comment

   Fast Fill is described as applicable to any transaction

   • Bug
     • At features/fast-fill.mdx:16, “Call Fast Fill on any transaction” implies that a caller can submit an arbitrary on-chain transaction to Fast Fill. The SDK requires requestId, documented as coming from a previous Relay quote/execute, and the protocol guide defines it as a Relay-level intent identifier that cannot be derived from on-chain data alone.
   • Cause
     • The introductory marketing copy omits the API's Relay-request eligibility constraint.
   • Fix
     • Replace “any transaction” with wording such as “an eligible Relay request after it is submitted” and retain the requirement that callers use the Relay requestId created by the quote/execution flow.

   _{Ran code and verified through T-Rex}

2. General comment

   Fast Fill incorrectly promises 1:1 output without requiring a fixed rate

   • Bug
     • The sentence says that Fast Fill combined with Price Stabilization and Fee Sponsorship makes payments “instant and exactly 1:1.” The local Price Stabilization documentation explicitly states that sponsorship does not mean 1:1 and gives fee-sponsored outputs of 100.05 and 99.95 USDT as the market rate changes. Its fixed-rate section assigns the 1:1 behavior to fixedRate: "1:1", limited to stablecoins supported as solver currencies.
   • Cause
     • The Fast Fill copy conflates Fee Sponsorship, which pays fee components, with Price Stabilization fixed rates, which lock the input:output exchange rate.
   • Fix
     • Replace the claim with wording that says Fast Fill makes completion immediate, Fee Sponsorship covers eligible fees, and exactly 1:1 stablecoin output requires a fixedRate: "1:1" quote on a supported solver stablecoin pair.

   _{Ran code and verified through T-Rex}

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

[greptile-apps]

Fast Fill only accepts Relay requests

“Call Fast Fill on any transaction” is misleading: Fast Fill accepts a Relay requestId created by a prior Relay quote and execution flow, not an arbitrary onchain transaction. An integrator following this instruction for a non-Relay payment cannot accelerate it. Scope this claim to eligible Relay requests submitted through Relay.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Artifacts

Focused Fast Fill eligibility validation source

• Read-only Python source that checks the targeted claim against local Relay contracts and safely probes the endpoint with a non-Relay transaction hash, ending with the Relay-request prerequisite.

Current documentation sentence at line 16

• Captured command output showing the checked-in Fast Fill sentence that says it can be called on any transaction, ending with the overbroad claim.

Fast Fill contract validation and safe API probe

• Captured execution output showing the prior quote/execute requestId requirement and the credential-free API rejection of a non-Relay transaction-hash probe, ending with confirmation that arbitrary transactions are not targets.

_{Ran code and verified through T-Rex}

[greptile-apps]

Fee sponsorship does not guarantee a 1:1 output

Fee Sponsorship covers fees but does not lock the exchange rate. The Price Stabilization documentation shows fee-sponsored USDC→USDT payments can output 100.05 or 99.95 USDT as the market rate moves. Exactly 1:1 requires a fixedRate: "1:1" quote and is limited to supported solver stablecoin pairs, so this sentence should distinguish sponsorship from a fixed-rate quote.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Artifacts

Focused validator source for Fast Fill’s 1:1 claim

• Python source reads the checked-out Fast Fill, Price Stabilization, and Fee Sponsorship documentation and tests sponsored-only versus fixed-rate conditions, showing that the claim can be evaluated from the local documentation contract.

Captured focused validator source

• Captured command output prints the exact validator source that was executed for both documentation-contract scenarios, showing the checks were reproducible.

Fee-sponsored-only validation output

• Executed sponsored-only validation shows Price Stabilization explicitly says sponsorship is not 1:1 and permits 100.05 or 99.95 USDT output, confirming Fee Sponsorship does not guarantee 1:1.

Fixed-rate validation output

• Executed fixed-rate validation shows exactly 1:1 requires `fixedRate: "1:1"` and supported solver stablecoins, confirming the needed constraint.

_{Ran code and verified through T-Rex}