rename Relay Fee to Platform Fee, adopt cost terminology - #382
rename Relay Fee to Platform Fee, adopt cost terminology#382ted-palmer wants to merge 4 commits into
Conversation
|
Claude finished @ted-palmer's task in 1m 54s —— View job Code review — PR #382
The rename direction is right and matches the API: 1. The rename stops at this file — five other in-scope pages still say "Relay fee"AGENTS.md §4.2 requires inbound references to the old name be updated in the same PR. Left stale:
Also worth a pass: the link text 2. Capitalization of the new cost terms is inconsistent within the fileThe numbered list and the 3.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
LGTM although the review job flagged some other areas for improvement |
n-xlkt
left a comment
n-xlkt
left a comment
There was a problem hiding this comment.
@ted-palmer just a few changes at the request of Ops
…to ted/update-fee-language
|
Claude finished @ted-palmer's task in 1m 54s —— View job Code review — PR #382
The rename direction is right and matches the API — Status: HEAD ( 1. Ops' requested changes aren't in yet — and one of them conflicts with the file@n-xlkt asked for
2. The rename still stops at this file — four other in-scope pages say "Relay fee"AGENTS.md §4.2 requires inbound references to the old name be updated in the same PR. Still stale:
Separately, the link text 3. Capitalization of the new cost terms is inconsistent inside the fileThe list and the 4.
|
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| Integrators with [Fee Sponsorship](/features/fee-sponsorship) enabled can subsidize fees for their users. By default, setting **`subsidizeFees`** to `true` sponsors all fee components. | ||
|
|
||
| For more granular control, use the **`sponsoredFeeComponents`** parameter in the quote request to choose which specific fee components to sponsor. This allows you to sponsor some fees (e.g. execution and relay fees) while letting the user pay others (e.g. swap fees). | ||
| For more granular control, use the **`sponsoredFeeComponents`** parameter in the quote request to choose which specific fee components to sponsor. This allows you to sponsor some components (e.g. `execution` and `platform`) while letting the user pay others (e.g. `swap`). |
There was a problem hiding this comment.
sponsoredFeeComponents is a quote-request enum, but this example uses platform, which is not an accepted value. Integrators who copy the example will submit an invalid quote request instead of sponsoring Relay's platform component. Replace platform with relay; platform should remain the name used for the v3 response field.
Artifacts
Fee documentation before the terminology change
- Captured the git diff showing the fee documentation before and after the PR change, including the changed sponsorship example.
Fee documentation after the terminology change
- Captured the current numbered fee-documentation lines and shows line 148 using `platform` as a sponsorship request value.
Executable Relay API fee contract check source
- The executable Python contract check fetches Relay's live OpenAPI and verifies v3, v2, quote, and sponsorship-enum fee fields.
Live Relay OpenAPI fee contract check output
- Executed the live OpenAPI and public v2 checks; it confirms all documented response fields and shows that quote sponsorship accepts `relay` but rejects `platform`, establishing the defect.
Relay endpoint runtime response capture
- Captured real endpoint responses: v3 without an API key returned HTTP 400 with the required-key message, v2 returned HTTP 200, and an empty quote request returned HTTP 400 with its validation message.
- Add "(formerly X Fees)" parentheticals to Execution Cost, Swap Cost, and Platform Fees per n-xlkt's requested changes - Make Platform Fees consistently plural throughout the doc - Remove the wholesale-cost-vs-fee explainer sentence per review - Update "Relay Fees" link text to "Platform Fees" in the docs that link to this page
|
Claude finished @ted-palmer's task in 3m 6s —— View job Code review — PR #382
New commit 1.
|
| Location | Reads |
|---|---|
fees.mdx:8 |
Execution Cost (singular) |
fees.mdx:17 |
Swap Cost (singular) |
fees.mdx:26 |
Platform Fees (plural) |
fees.mdx:108 |
App Fees (plural) |
fees.mdx:132–135 (<Tip>) |
Execution Cost, Swap Cost, Platform Fees, App Fee (singular!) |
So app is plural in the heading and singular in the <Tip> mapping 27 lines later, and platform is the reverse of execution/swap. AGENTS.md §5 doesn't settle number, but the page should agree with itself.
Independent of which number you pick, fees.mdx:124 is now ungrammatical:
platform - The Platform Fees, a flat basis-point fee charged by Relay…
A plural subject in apposition with a singular predicate. fees.mdx:51 has a milder version ("a revenue share on the Platform Fees", previously "on the Relay Fee"). Singular "Platform Fee" fixes both and matches the API's own data.platformFee field; if Ops wants the plural heading kept, :124 needs rewording instead (e.g. "Platform Fees — the flat basis-point fee charged by Relay…").
4. Five inbound references still say the old name (§4.2)
AGENTS.md §4.2 requires inbound references to the old name be updated in the same PR:
| File | Line | Text |
|---|---|---|
features/price-stabilization.mdx |
1301 | "the flat execution fee … and the Relay bps fee as the dominant costs" |
references/api/api_core_concepts/trade-types.mdx |
13, 18, 25 | "relay fees, app fees, and gas fees" (×3) |
features/fee-sponsorship.mdx |
52 | "sponsor specific Relay fees … (such as gas fees or relayer fees)" |
features/fee-sponsorship.mdx |
212 | "designed to cover relay and execution costs" |
solutions/payment-service-providers.mdx |
46 | "its execution, swap, and Relay fee components … revenue share on the Relay fee" |
Two of these stand out:
price-stabilization.mdx:1301is the sentence immediately above the line this PR edited. The link label on:1303was updated and "the Relay bps fee" two lines up was not — the same paragraph now uses both vocabularies.fee-sponsorship.mdx:52is thesponsoredFeeComponentstable row, and "gas fees or relayer fees" names components that have never existed in that enum. Whatever you settle in item 1, this row should list the real values.
5. The (formerly …) parentheticals put the page in silent violation of §4.2
AGENTS.md §4.2 says to edit in place and not leave an old-version trace inline; the record belongs in references/api/changelog.mdx (current through 2026-08-19, no entry for this rename). The three parentheticals Ops asked for are exactly such traces.
Ops' searchability argument is the right call — but then the checked-in guide is out of date, and the honest fix is to amend §4.2 with a one-line exception ("user-facing terminology renames may carry an inline (formerly X) alias") rather than leave a reviewer request and the style guide pointing opposite directions. Cheap to do in this PR; a changelog entry the alias can point at would also give the parentheticals somewhere to retire to later.
6. Nit — docs.json redirect
docs.json:389 redirects to this page; worth a glance that the source path isn't itself named after the old terminology. Not blocking.
Not checked: no lint or build ran — this repo wires no MDX test suite, and network egress is blocked in this checkout, so I could not fetch the OpenAPI spec to settle item 1 first-hand or confirm the raw <table> blocks at :30/:60 render. Both are visible in the preview deploy.
No changes pushed — this was a review, not an implementation request.
• branch ted/update-fee-language
|
All six findings check out against the file contents. A few priority notes: Issue 1 is the only API-breaking bug. Issue 3 is a real grammar error, not just a style nit. Line 124:
"The Platform Fees … a flat basis-point fee" is an ungrammatical appositive. Easiest fix while keeping the plural heading Ops wanted: use an em-dash instead of an appositive — "Platform Fees — the flat basis-point fee charged by Relay…" — which avoids the number clash. The Issue 4 is incomplete propagation, already required by AGENTS.md §4.2. The two clearest stragglers:
Issues 2, 5, 6 are lower-severity but worth bundling in: "Platform Fees" as link text for a page titled "Fee Structure" that covers four components is a tighter mismatch than what it replaced, and For issue 5, agree that the honest path is a one-line §4.2 carve-out in AGENTS.md plus a changelog entry — both are cheaper to add in this PR than to unwind the Tip: You can customize Greptile's behavior for this repo with |
|
The live API response embedded in "feeSponsorship": {
"quoted": {
"selectedComponents": ["execution", "swap", "relay", "app"],So All six items check out against the files. A few additions: Item 1 — The asymmetry you flagged (request Item 3 — The Item 4 — Item 5 — Agreed on the framing. Adding a one-line exception to §4.2 with a pointer to a changelog entry is cleaner than leaving the guide and style guide pointing opposite directions. A changelog entry also gives the parentheticals a natural retirement path when the alias becomes unnecessary. |
| Integrators with [Fee Sponsorship](/features/fee-sponsorship) enabled can subsidize fees for their users. By default, setting **`subsidizeFees`** to `true` sponsors all fee components. | ||
|
|
||
| For more granular control, use the **`sponsoredFeeComponents`** parameter in the quote request to choose which specific fee components to sponsor. This allows you to sponsor some fees (e.g. execution and relay fees) while letting the user pay others (e.g. swap fees). | ||
| For more granular control, use the **`sponsoredFeeComponents`** parameter in the quote request to choose which specific fee components to sponsor. This allows you to sponsor some components (e.g. `execution` and `platform`) while letting the user pay others (e.g. `swap`). |
There was a problem hiding this comment.
The example tells integrators to send platform in sponsoredFeeComponents, but that quote-request enum uses relay. A live POST /quote/v2 request with platform returns HTTP 400, while the same request with relay succeeds. Change the example to execution and relay; otherwise, integrators who copy it will submit invalid sponsorship quote requests.
Artifacts
Prior documentation version showing the sponsorship example
- Captured the parent revision of the cited fee documentation and its history, showing that the same `execution` and `platform` sponsorship example predates current HEAD; the takeaway is that the invalid example was carried into the current documentation.
Live quote contract probe source
- Shell probe fetched Relay’s live OpenAPI document and sent identical public quote requests using `platform` and `relay`; the takeaway is that the source directly exercises the documented request contract.
Live OpenAPI and quote endpoint responses for platform and relay
- Captured output of the executed probe: the live enum excludes `platform`, `platform` returned HTTP 400 with its validation message, and `relay` returned HTTP 200; the takeaway is that the documentation’s suggested value is rejected.
Current documentation lines and declared OpenAPI authority
- Captured the current file lines 138–150 plus repository declarations that the live OpenAPI schema is the API-reference source of truth; the takeaway is that exact current line 146 conflicts with the authoritative contract.
|
Claude finished @ted-palmer's task in 2m 28s —— View job Code review — PR #382
New commit Four things still open. 1.
|
| Location | Reads |
|---|---|
:8 |
Execution Cost — singular |
:17 |
Swap Cost — singular |
:26 |
Platform Fees — plural |
:108 |
App Fees — plural |
:132–135 (<Tip>) |
Execution Cost, Swap Cost, Platform Fees, App Fee — app flips to singular |
The <Tip> needs app → App Fees to agree with :108 regardless of which convention you settle on; right now the same component is plural in the heading and singular in the mapping 27 lines below it.
3. Stale inbound references (§4.2) — two of them on lines this PR edited
AGENTS.md §4.2 requires inbound references to the old name be updated in the same PR. Six remain, and they're not all the same case:
Same line / same paragraph as an edit — these read as oversights:
solutions/payment-service-providers.mdx:46— the PR changed the link label on this exact line and left "its execution, swap, and Relay fee components … revenue share on the Relay fee" in the same sentence.features/price-stabilization.mdx:1301—:1303was updated; the sentence directly above still says "the Relay bps fee", so one paragraph now carries both vocabularies.
Generic prose, straightforward renames:
references/api/api_core_concepts/trade-types.mdx:13,18,25— "relay fees, app fees, and gas fees" (×3).features/fee-sponsorship.mdx:212— "designed to cover relay and execution costs".
One that's wrong independent of this rename:
features/fee-sponsorship.mdx:52— thesponsoredFeeComponentstable row says integrators can cover "different fee types (such as gas fees or relayer fees)". Neither has ever been a member of that enum. Whatever you decide in item 1, this row should name the real values.
One nuance worth deciding rather than bulk-replacing: payment-service-providers.mdx:46 is describing expandedPriceImpact, which per fees.mdx:139 genuinely names the component relay. So "Relay fee components" there is arguably accurate as-is — a blind rename to "Platform Fee" would make it wrong. Either scope the sentence to v3 (data.fees → platform) or keep relay and say which object it belongs to. The trade-types.mdx and fee-sponsorship.mdx:212 instances have no such tie to a field name and rename cleanly.
4. AGENTS.md §5 should gain the new terms, and §4.2 still points against the parentheticals
Two guide-level loose ends, both cheap here and expensive later:
- §5 Terminology has no entry for any of these. This PR is establishing Execution Cost, Swap Cost, Platform Fees, and App Fees as canonical, and §5 is what the drift-draft automation reads (
docs(drift):commits are most of recentmain). Without entries there, the next generated draft has nothing stopping it from reintroducing "Relay fee". Four lines in §5 make this rename stick. - §4.2 says not to leave an old-version trace inline — the three
(formerly …)parentheticals are exactly that. Ops' searchability argument is right, so the guide is what's out of date; add a one-line carve-out ("user-facing terminology renames may carry an inline(formerly X)alias") rather than leaving the page in silent violation of a checked-in rule.
There's also no references/api/changelog.mdx entry (current through 2026-08-19). Arguably optional since no API field changed — but the <Tip> rewrite is a real consumer-facing change, not a rename: it splits what was one Swap Impact line into separate Execution Cost and Swap Cost lines and drops Provider Fee / Your App's Fee. Anyone who built UI against the old mapping needs a layout change. That deserves a record somewhere, and it gives the parentheticals somewhere to retire to.
Not verified: no lint or build ran — this repo wires no MDX test suite, and network egress requires approval here, so I could not fetch the OpenAPI spec first-hand (item 1 rests on in-repo live captures plus @greptile-apps' probes) or confirm the raw <table> blocks at :30/:60 render. Both are visible in the preview deploy.
No changes pushed — this was a review, not an implementation request.
• branch ted/update-fee-language
|
The analysis is accurate. I've verified the four issues against the current files. Here's my assessment prioritized by severity: Issue 1 is a functional bug. Issue 3 has two tiers. The Issues 2 and 4 are editorial/process, not breaking. The grammar fix at Suggested merge order: fix issue 1 now (it's one token), fold issues 2 and 3 into the same commit to keep the diff reviewable, then address AGENTS.md in a follow-up if that's a separate ownership concern. |
|
All four findings verified against the files. Here's what the source confirms: Issue 1 — confirmed, definitive. The For the Note extension: the response captures also confirm the v3 asymmetry is real — Issue 2 — confirmed. "platform - The Platform Fees, a flat basis-point fee" is the exact text. Plural noun, singular appositive — ungrammatical as written. And the Issue 3 — confirmed, with the nuance you flagged holding up.
The first "Relay fee components" is genuinely ambiguous — Issue 4 — Without AGENTS.md in view I can't verify the §5 gap directly, but the structural argument stands: without entries for Execution Cost, Swap Cost, Platform Fees, and App Fees, the next drift-draft commit has nothing to anchor to, and the |
|
Feedback addressed. I also updated the page title to "Cost & Fee Structure". Lmk if we don't want to do that though |
| Integrators with [Fee Sponsorship](/features/fee-sponsorship) enabled can subsidize fees for their users. By default, setting **`subsidizeFees`** to `true` sponsors all fee components. | ||
|
|
||
| For more granular control, use the **`sponsoredFeeComponents`** parameter in the quote request to choose which specific fee components to sponsor. This allows you to sponsor some fees (e.g. execution and relay fees) while letting the user pay others (e.g. swap fees). | ||
| For more granular control, use the **`sponsoredFeeComponents`** parameter in the quote request to choose which specific fee components to sponsor. This allows you to sponsor some components (e.g. `execution` and `platform`) while letting the user pay others (e.g. `swap`). |
There was a problem hiding this comment.
sponsoredFeeComponents is sent to the quote API, whose accepted component name for Relay's platform fee is relay, not platform. A live /quote/v2 request accepts relay through enum validation but rejects platform as unsupported. Change this example to use execution and relay; otherwise, integrators copying it will receive an invalid quote request.
|
Want your agent to iterate on Greptile's feedback? Try greploops. |
3 participants
No description provided.