docs: clarify fixedRate and subsidizeFees are independent

[pedromcunha]

The fixed-rate section only documented the sponsored configuration: its worked figures assume subsidizeFees: true and the only request example passes it, so integrators read fee sponsorship as a prerequisite for fixed rates. Document the subsidizeFees: false case, and describe fixedRateFee as a quote-time estimate rather than the settled amount.

[github-actions]

Claude encountered an error after 3m 37s —— View job

---

Code review — PR #464

• Fetch the PR diff
• Read features/price-stabilization.mdx in full for context
• Check claims against related docs (fee sponsorship, fees, quote API)
• Verify style-guide conformance (AGENTS.md)
• Post review

Note on method: gh pr diff and network fetches weren't permitted in this run, and the checkout is a single squashed commit where HEAD == origin/main, so I couldn't read the literal unified diff. I reviewed the merged state of features/price-stabilization.mdx and reconstructed the added regions from the PR description and line-count (+31/-1): line 657, the **Fixed rates without fee sponsorship.** block at 676–684, and the **Tracking what you sponsored or earned.** block at 1311–1327. If any of my line attributions land on pre-existing text, I've said so.

---

Verdict

The arithmetic is correct and the new model is self-consistent with the rest of the page — I checked it end to end. Taking "a fixed rate pins the pre-fee output" as the model:

Scenario	market pre-fee	fixed pre-fee	spread	fee	matches doc?
1:1, subsidize on, rate 1.0005 (L661)	99.95	100	−0.05	−0.03	sponsor $0.08 ✅
1:1.0005, subsidize on, rate 1.0000 (L672)	100	99.95	+0.05	−0.03	earn $0.02 ✅
1:1, subsidize off, rate 0.9995 (L681, new)	100.05	100	+0.05	user pays	earn $0.05 ✅
1:1, subsidize off, rate 1.0005 (L682, new)	99.95	100	−0.05	user pays	sponsor $0.05 ✅

The new figures also reconcile against the live response body already on the page: fixedRateFee.usd: "-0.049092" (L1168) ≈ the −$0.05 spread, and sponsored.usd: "0.072452" (L1148) ≈ 0.049 + 0.023 fee — which is exactly the $0.08 sponsored case. Quoting -0.049092 verbatim in the new snippet rather than inventing a number is the right call under AGENTS.md §1.2.

Two things I'd follow up on.

---

1. The new section says the settings are independent, then the Warning reveals a shared prerequisite

features/price-stabilization.mdx:676

fixedRate and subsidizeFees are independent settings — you can pass a fixed rate with "subsidizeFees": false.

Read on its own, an integrator concludes that fixed rates need no fee-sponsorship setup. But the Warning added at features/price-stabilization.mdx:1325 says the settled amount "settles against your sponsoring wallet's balance" — and when the market moves against you (the 1.0005 row at L682, "you sponsor $0.05"), that balance has to be funded. Per features/fee-sponsorship.mdx:20-22, that means an API key, a linked Fee Sponsorship Wallet, and a funded app balance — the same three requirements as sponsorship.

So the parameters are independent, but the infrastructure isn't. The section is 600 lines away from the Warning that discloses this. Worth one sentence at L684 along the lines of: turning off subsidizeFees moves the Relay fee onto the user, but you still need a funded app balance to settle the fixed-rate spread when it goes against you.

Fix this →

---

2. "your sponsoring wallet's balance" doesn't match the established terminology

features/price-stabilization.mdx:1325

The rest of the docs draw a distinction the new Warning collapses: the Fee Sponsorship Wallet is the wallet that funds your app balance, and fees are drawn from the app balance, not from the wallet (features/fee-sponsorship.mdx:21-22, and snippets/AppBalance.mdx is the shared explainer imported wherever this comes up). "Settles against your sponsoring wallet's balance" reads as a direct debit from the linked wallet, which as far as I can tell from the docs isn't what happens.

Suggest "settles against your app balance." This is the only place in price-stabilization.mdx that names the funding source, so it's also the one line an integrator will anchor on.

Fix this →

---

Smaller notes

The remaining request example still pairs the two. The PR description identifies "the only request example passes subsidizeFees: true" as part of the confusion, but the <CodeGroup> at features/price-stabilization.mdx:688-707 is unchanged and still sends both. The prose now corrects the reading, though a reader who skims to the copy-paste block lands back where they started. A one-line note under the example ("subsidizeFees is independent here — drop it to have the user pay the fee") would close the loop more cheaply than a second <CodeGroup>.

Pre-existing, but now load-bearing: features/price-stabilization.mdx:670 says the rate is expressed as input:output, yet 1:1.0005 is shown yielding 99.95 USDT from 100 USDC (L672-674) — input/1.0005, not input × 1.0005. The new text asserts a precise model ("a fixed rate always pins the pre-fee conversion"), which makes the format ambiguity directly above it more likely to trip someone up. Not introduced here; worth a separate fix.

Style (AGENTS.md §2.9): prose parameter references should be bold+backticks (**`fixedRate`**); the new text uses plain backticks. That said, plain backticks are what this file does nearly everywhere — **\solverCurrencies`**` at L686 is the lone exception — so this is consistency-with-the-file vs. consistency-with-the-guide. Flagging, not blocking.

Unverifiable from this repo: fixedRate appears in no other doc and isn't in either changelog, so the behavioral claims — that subsidizeFees: false is a supported combination with fixedRate, and that the fixed rate pins pre-fee rather than post-fee output — rest entirely on this page. They're internally consistent with every worked example and with the captured API response, but I couldn't check them against solver or the OpenAPI spec. Worth a confirmation from someone with upstream access.

No changes pushed — this was a review.
· branch claude/pr-464-20260911-2126

[greptile-apps]

Confidence Score: 4/5

The exact-output wording is non-blocking, but it can lead integrators to promise an amount the documented fee model does not guarantee.

Findings

1.  Variable Fees Break Exact Output ▶

Summary

• Summary

• The new fixed-rate example presents an exact post-fee output even though Relay’s documented fee model includes route- and execution-dependent components. Update the example to describe the fixed rate as a pre-fee conversion and direct integrators to the quote’s returned output and fee breakdown.

• T-Rex validation blocked

• A live quote for this configuration requires a Relay API key, which was not available. The endpoint returned an authorization error before it could provide the quoted output or fees.

• Merge safety

• This is a non-blocking documentation concern, but correcting the exact-output statement will prevent integrators from making unsupported user-facing promises.

_{Reviews (1) · Last reviewed commit: "docs: clarify fixedRate and subsidizeFee..."}

[greptile-apps]

Variable Fees Break Exact Output

This introduces the fee as approximately $0.03 but then guarantees that the user receives exactly 99.97 USDT “at any market rate.” Relay fees include variable components, and this page’s own quote example shows a different sponsored-fee total. A fixed rate pins the pre-fee amount, but it does not guarantee this exact post-fee output. Integrators relying on this statement could promise an amount that the resulting quote does not deliver; keep the amount approximate and direct readers to the quote’s actual output and fee fields.

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!

_{Ran code and verified through T-Rex}