docs: clarify same-chain gasless swap limitations (INT2-266)

[pedromcunha]

Same-chain ERC-20 -> ERC-20 quotes ignore usePermit and return approve + swap transaction steps; forceSolverExecution is required to get the permit flow. Document what forceSolverExecution changes, and distinguish the Gasless Swaps page from the Gasless Execution (/execute) page.

[github-actions]

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

---

Code review: PR #454

Read both changed files plus references/api/api_core_concepts/step-execution.mdx, features/app-fees.mdx, and AGENTS.md. The framing is a genuine improvement — the Gasless Swaps / Gasless Execution split is the right disambiguation, and the forceSolverExecution consequences list (two legs, fees move to output, solver liquidity) is the kind of detail integrators actually get burned by.

I could not verify the API-level claims (usePermit being ignored, forceSolverExecution semantics) against https://api.relay.link/documentation/json — no network access in this environment. Everything below is an internal-consistency conflict with another page in this repo or with the page's own text.

---

1. authorize1 vs authorize2, and "planned" contradicts an already-documented step

features/gasless-swaps.mdx:180 says forceSolverExecution returns "the permit signature step (authorize1)". But references/api/api_core_concepts/step-execution.mdx:245 documents authorize1 as "Main flow for cross-chain permits" and authorize2 as "Same-chain swap permits" — and the authorize2 example at :477 is a same-chain Base (chainId: 8453) USDC PermitBatchWitnessTransferFrom posting to /execute/permits with "api": "user-swap".

Two problems fall out of this:

• Wrong step ID (if authorize2 is right). An integrator branching on step id handles the wrong case and the flow silently never advances.
• :183 — "Native permit support for same-chain ERC-20 → ERC-20 swaps without forceSolverExecution is planned" reads as "doesn't exist yet", while step-execution.mdx documents a shipped same-chain permit step with a concrete example. One of the two pages is wrong.

If the reconciliation is that authorize2 is same-chain self-executed permit and only covers particular route shapes (e.g. not ERC-20 → ERC-20), that distinction is the whole point of this PR and needs to be stated on both pages. Per AGENTS.md §4.2, the related page has to be updated in the same PR.

Fix this →

2. The decision tree still routes readers straight into the broken flow

features/gasless-swaps.mdx:22. The page opens by telling the reader "We've put together a decision tree below to help you arrive at the solution that best fits your application" — that tree is the page's entry point. It still sends every BYO-wallet reader to Permit-based Gasless with _Limitation: not all ERC-20s support permit_ as the only caveat, and has no same-chain branch. A reader who follows the tree as instructed lands on exactly the flow this PR says doesn't work, and only finds out if they keep scrolling past the node they were told to click.

Either add a same-chain branch or extend the Permit node's limitation label (e.g. _Limitation: not all ERC-20s support permit; same-chain needs forceSolverExecution_).

Fix this →

3. The ERC-4337 / 7702 table row dead-ends

features/gasless-swaps.mdx:181 says both are "Supported through /execute" same-chain, with fee sponsorship the only extra requirement. But those two sections tell you to batch approve + deposit (:96 "batches approve + deposit calls via executeBatch", :148 "atomically combines approve() and deposit()"), and the new section directly above states a same-chain quote returns approve + swap — there is no deposit step to batch.

A reader following the 4337 steps on a same-chain route has nothing to put in the batch. The row should say what to wrap on a same-chain quote (the swap call), or note that forceSolverExecution applies here too and the deposit step comes back.

Fix this →

4. /execute calls are not signed

features/gasless-execution.mdx:7 — "raw calls that you have already built and signed". Nine lines below, the page's own body (:16) says the API "allows users to submit raw calls (the partial payload of a regular EVM transaction). It includes the to, data, value and an optional EIP-7702 authorizationList" — no signature field, and the page's first example submits unsigned deposit calldata. What's signed is the payload wrapped inside the call (a UserOp, a 7702 authorization), not the call. Since this <Info> is now the first thing on the page, it's worth being precise: "raw calls that you have already built (to/data/value, plus an optional 7702 authorizationList)".

Fix this →

5. features/app-fees.mdx still claims same-chain app fees are fully supported

The new <Info> at gasless-swaps.mdx:197 documents a real quote-time failure — same-chain txs + app fees when the input token isn't solver-held. features/app-fees.mdx:42 still shows Swaps (same-chain) | ✅ and :52 says "EVM (same-chain): Fully supported." App-fee integrators who never open the gasless page won't see the caveat. app-fees.mdx:25 already describes the extra in-transaction swap that's the mechanism here, so that's the natural place for a one-line note plus a link.

Fix this →

6. Top warning is broader than the limitation it describes

features/gasless-swaps.mdx:41 now reads "none of the flows below are gasless on a same-chain route without extra parameters", while :53 and the table at :180 both scope the permit limitation specifically to ERC-20 → ERC-20. Same-chain routes with a native leg are left unspecified — a team running a working same-chain ERC-20 → native permit swap reads the top warning as "you're broken." Worth either scoping the warning to match, or saying explicitly what happens on same-chain routes involving the native token.

Style notes (AGENTS.md)

• §2.7 — "Keep cell descriptions concise; move long explanations into prose below the table." Both cells in the new Same-chain swaps table run 3–4 sentences with inline links. Two ### subsections (or prose paragraphs) would read better than a two-row table doing paragraph duty.
• §2.5 — callouts are "reserved for quick pointers." The Permit-based Gasless section now stacks two <Warning>s back to back (:47 and :53), and the top of the page has an <Info> immediately followed by a <Warning>. Consider merging each pair.
• The orientation <Info> at :35 sits after the decision tree. Its job is to bounce readers who are on the wrong page, so it lands better directly under the intro paragraph, before ## What solution is right for me?.

---

No changes were made — this is review feedback only. Findings 1–3 are the ones I'd want resolved before merge; 1 in particular because it puts two pages in direct conflict about whether a shipped feature exists.
· pedro/int2-266-clarify-same-chain-gasless-swap-limitations

[github-actions]

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

---

Review: PR #454 — clarify same-chain gasless swap limitations

• Gather context (read PR diff)
• Read AGENTS.md style guide + surrounding pages
• Verify claims: links, anchors, referenced params
• Post review

The diff is a single 4-line <Warning> in features/gasless-swaps.mdx. The behavior it describes is useful and the placement (under Permit-based Gasless, right before the ### How it works Steps that tell you to call /quote/v2 with usePermit: true) is the right spot. Findings below, most important first.

---

1. forceSolverExecution is documented nowhere else in the repo

features/gasless-swaps.mdx:49 is the only occurrence of forceSolverExecution in the whole docs site (grepped the full tree — no hits in references/api/, api_core_concepts/, references/relay-kit/, or the changelog). The reader is told to pass a parameter but not:

• which request it goes on — the page names /quote/v2 explicitly everywhere else (lines 56, 83, 128), so this line should too;
• what it actually changes — "get the permit flow" is the effect, not the mechanism. Presumably it routes the swap through the solver instead of executing directly against the DEX, which is why the permit becomes possible and also what has price/fee implications. The PR description says the goal is to "document what forceSolverExecution changes" — as written, the diff documents only that you should set it.

This is the main gap between the stated intent and the diff. AGENTS.md §2.6 also asks you to link on first mention of a concept that has its own page; if this flag has no home page yet, a one-line explanation of the tradeoff in the callout is the minimum.

Fix this →

2. The new callout doesn't connect to the same-chain constraint already on the page

features/gasless-swaps.mdx:36-38 already warns: "Same-chain gasless swaps are only supported if you sponsor the fees. Same-chain swaps route directly through DEXes, due to this the solver never has an opportunity to deduct the gas fees before the user gets the destination token."

That warning and the new one are the same story from two angles — direct-DEX routing is why fees can't be deducted and why there's no permit step. A reader who follows the new instruction gets a permit flow but presumably still needs fee sponsorship, and nothing on the page says so. Either fold the new text into the existing warning, or add "you still need fee sponsorship" to it. Worth confirming with the API team whether forceSolverExecution changes that constraint at all — if solver execution does let fees be deducted, the line 36–38 warning is now partly stale and should be updated in the same PR.

3. <Info> fits better than a third <Warning>

AGENTS.md §2.5 scopes <Warning> to "critical warnings (security-sensitive usage, deprecations, breaking constraints)" and <Info> to "additional context or side-notes that aren't warnings". §3.1 specifically lists "inline <Info> callouts (for parameter-specific notes)" as the feature-guide pattern — which is exactly what this is. The page now has two consecutive <Warning> blocks (lines 44–46 and 48–50) plus one at the top, which flattens the severity signal.

Fix this →

4. Possible contradiction with step-execution.mdx

references/api/api_core_concepts/step-execution.mdx:479 documents the authorize2 step as "Sign authorization for same-chain swap permits using PermitBatchWitnessTransferFrom." Read on its own that says same-chain permits exist; the new warning says they don't "on their own". The two reconcile if authorize2 is what you get once forceSolverExecution is set — but nothing states that. A cross-link in one direction would close the loop.

5. Scope: the second half of the PR description isn't implemented

The description also says to "distinguish the Gasless Swaps page from the Gasless Execution (/execute) page." Neither features/gasless-swaps.mdx nor features/gasless-execution.mdx links to the other today, and the diff doesn't add anything for this. Intentional follow-up, or dropped?

6. Nits

• Indentation — every other callout on the page indents its body two spaces (lines 37, 45, 131); the new one starts at column 0. Cosmetic, but inconsistent within the same file.
• ERC-20 vs ERC20 — the new line uses ERC-20, the warning directly above it (line 45) uses ERC20. The page is already mixed (line 124 uses ERC-20); AGENTS.md §5 doesn't rule on it, so this is only a within-section consistency nit.

---

Verification note: I could not reach https://api.relay.link/documentation/json from this sandbox (no network egress), so the claims about usePermit being silently ignored and about forceSolverExecution's existence and semantics are unverified against the OpenAPI spec — they're taken at face value from the PR description. Everything else above is verified against the repo.
· pedro/int2-266-clarify-same-chain-gasless-swap-limitations

[github-actions]

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

---

Code review: docs: clarify same-chain gasless swap limitations (INT2-266)

• Gather context (read PR diff)
• Read AGENTS.md style guide + surrounding pages
• Verify claims: links, anchors, referenced params
• Post review

---

The diff is a single 4-line <Warning> on features/gasless-swaps.mdx:48-50. The claim it makes is plausible and the step-id vocabulary it uses (approve, swap) is real — references/api/api_core_concepts/step-execution.mdx:253 documents the approve → swap flow for same-chain swaps. But the change contradicts another page, and it delivers roughly a third of what the PR description promises.

1. Contradicts step-execution.mdx on same-chain permits

references/api/api_core_concepts/step-execution.mdx currently documents same-chain permits as a supported, ordinary outcome:

• Line 244 — flow table: `authorize2` · "Sign to approve transfer of tokens" · "Same-chain swap permits."
• Line 475 — ### authorize2 · "Sign authorization for same-chain swap permits using PermitBatchWitnessTransferFrom."

The new warning says same-chain ERC-20 → ERC-20 swaps "do not support the permit flow." A reader who follows the decision tree to Permit-based Gasless is told same-chain permits don't happen; a reader who lands on the step-execution reference is shown a fully worked Permit2 signature step for exactly that case, with no caveat.

The on their own hedge is presumably doing the reconciling work (authorize2 appears once forceSolverExecution is set — see #2), but nothing on either page says so. Whichever way it resolves, both pages should say the same thing in the same PR: either annotate the authorize2 table row and section with the flag that produces it, or narrow the new warning to the default-quote case and point at authorize2.

Fix this →

2. The warning names a limitation with no remedy

The PR description says forceSolverExecution is required to get the permit flow, and that this PR should "document what forceSolverExecution changes." It doesn't — grep -ri forceSolverExecution over the repo returns zero hits, before and after this diff.

As shipped, the warning tells an integrator their flow silently degrades and stops there. "on their own" implies an escape hatch exists but never names it, which is the worst version of this callout: enough to worry the reader, not enough to unblock them. The one sentence that carries the actual value of INT2-266 is the missing one.

Fix this →

3. "Distinguish Gasless Swaps from Gasless Execution" is not addressed

Also promised in the description, also absent. The two pages have never linked to each other in either direction — features/gasless-swaps.mdx links to /references/api/execute twice (lines 79, 150) but never to /features/gasless-execution, and features/gasless-execution.mdx never mentions Gasless Swaps. They sit two entries apart in docs.json (lines 47, 49) with near-identical names, which is exactly the confusion the description is trying to fix.

If this is deferred to a follow-up, worth saying so on the PR so it isn't lost — the description currently reads as if it shipped.

4. Style — stacked callouts (AGENTS.md §2.5)

Three <Warning> blocks on one page now, two of them back-to-back at lines 44–50, both about permit-flow constraints. Consecutive warnings dilute each other; §2.5 reserves callouts for "quick pointers." Two options:

• Merge lines 44–46 and 48–50 into one <Warning> covering ERC-20 permit constraints, or
• Demote the new one to <Info> — it describes a behavior boundary rather than a hazard, which is what §2.5 scopes <Info> to.

Separately, the new block doesn't indent its content two spaces, unlike every other callout on the page (lines 37, 45, 131).

5. Nit — ERC20 vs ERC-20 on adjacent lines

Line 45 says ERC20, the new line 49 says ERC-20. AGENTS.md §5 doesn't pin this one, and the page is already mixed (line 124 uses ERC-20), but the two spellings are now four lines apart. Cheap to normalize to ERC-20 while you're here.

---

Summary: the factual core is sound and the step-id terminology checks out. Blocking concern is #1 (a direct contradiction with step-execution.mdx that this PR creates), closely followed by #2 (the callout raises a problem it declines to solve). #3 is a scope gap against the stated intent. #4 and #5 are style.

No changes were implemented — this was a review-only request. Repo has no linter or test suite wired for MDX, so nothing was run beyond reading and grepping.
· pedro/int2-266-clarify-same-chain-gasless-swap-limitations

[greptile-apps]

Greptile Summary

This update clarifies the documented behavior of gasless swap quote steps.

Confidence Score: 5/5

No blocking failure remains.

No blocking failure remains.

T-Rex Logs

What T-Rex did

• T-Rex ran the requested verification, but its local artifact references were not uploaded.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "docs: reconcile step-execution authorize..." | Re-trigger Greptile}

[greptile-apps]

Same-chain permit route omits the solver flag

usePermit: true alone produces the documented self-executed transaction flow for same-chain ERC-20 swaps, but readers are not told how to obtain the permit flow. A live Base USDC → WETH quote returned a swap transaction step with usePermit alone and an EIP-712 authorize1 signature step when forceSolverExecution: true was added. Explain that callers must include forceSolverExecution: true to route through the solver and receive permit instructions; otherwise the adjacent permit-based instructions leave same-chain integrators unable to implement this supported flow.

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

Same-chain permit quote comparison script

• A narrowly scoped Python script made two non-mutating Relay quote requests that differ only by the solver-routing flag, providing the executable verification method.

Live quote response with usePermit alone

• Executed the same-chain Base USDC-to-WETH quote using `usePermit: true` only and captured HTTP 200 OK with a transaction `swap` step and no signature step.

Live quote response with usePermit and forced solver execution

• Executed the identical quote with `forceSolverExecution: true` added and captured HTTP 200 OK with an EIP-712 signature `authorize1` step, proving the omitted requirement.

_{Ran code and verified through T-Rex}

[github-actions]

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

---

Code review: PR #454 — clarify same-chain gasless swap limitations

• Gather context (read PR diff)
• Read AGENTS.md style guide + surrounding pages
• Verify claims: links, anchors, referenced params
• Post review

---

Reviewed the current head (f996b86) against origin/main. Two files, ±3 lines. The revision fixed real problems from the previous round — the stacked <Warning>s are merged, ERC20/ERC-20 is normalized on gasless-swaps.mdx, and step-execution.mdx no longer flatly contradicts the feature page. Both new links resolve: ## Permit-based Gasless → #permit-based-gasless ✅ and ### authorize2 → #authorize2 ✅.

But the rewrite dropped the one thing INT2-266 was for, and it did so while making the claim stronger. That's the blocking issue.

---

1. forceSolverExecution is gone, and the hedge went with it

Commit 0e07d20 said same-chain ERC-20 → ERC-20 swaps "do not support the permit flow on their own." Commit f996b86 deleted that qualifier. features/gasless-swaps.mdx:45 and references/api/api_core_concepts/step-execution.mdx:479 now both assert a categorical impossibility:

Same-chain ERC-20 → ERC-20 swaps do not support the permit flow: passing usePermit: true is ignored…

Greptile's T-Rex run on this very PR contradicts that. It executed two live quotes differing only by one flag: Base USDC → WETH (both ERC-20, same chain) returned a transaction swap step with usePermit: true alone, and an EIP-712 signature step with forceSolverExecution: true added. grep -r forceSolverExecution over the repo still returns zero hits.

So as it stands, the docs tell an integrator a supported flow is impossible. The PR description says the goal is to "document what forceSolverExecution changes" — the current diff documents neither the flag nor its existence, and the hedge that used to leave room for it has been removed. Net of both commits, this is a step backward on the PR's stated purpose. Restore "on their own" at minimum; better, name the flag and its tradeoff (routing through the solver rather than direct-to-DEX, which is what makes the permit possible and what has fee implications).

Fix this →

2. The authorize1 / authorize2 split may be reconciled in the wrong direction

The same T-Rex run reports the solver-routed same-chain permit came back as authorize1, not authorize2. If that holds, this PR's reconciliation misses in two places it leaves untouched:

• step-execution.mdx:244 — authorize1 · "Main flow for cross-chain permits"
• step-execution.mdx:257 — flow table · authorize1 · "Cross-chain permit-based transfer (gasless)"

Both would be wrong, and there'd be no page anywhere describing the same-chain authorize1 an integrator actually receives. Per AGENTS.md §4.2, inbound references get updated in the same PR.

Separately, the new narrowing of authorize2 to "same-chain ERC-20 → native" isn't supported by anything I can see in the repo. The authorize2 example at :477 is a Base (chainId: 8453) USDC PermitBatchWitnessTransferFrom posting to /execute/permits with "api": "user-swap" — it never names the output token, and its single call3Value is an approve (0x095ea7b3) back against USDC, which doesn't disambiguate native vs. ERC-20 output either. Where does the ERC-20 → native restriction come from? If it's from a solver-side read, worth saying so in the PR so a reviewer can check it; if it's inferred, it's a strong claim to put on a reference page.

Fix this →

3. The new exception contradicts the top-of-page warning

gasless-swaps.mdx:37 (unchanged) explains the same-chain constraint by mechanism:

Same-chain swaps route directly through DEXes, due to this the solver never has an opportunity to deduct the gas fees before the user gets the destination token.

:45 now says same-chain ERC-20 → native does return a solver permit step. A permit step exists precisely because the solver is executing — so "same-chain routes directly through DEXes, solver never gets a chance" can't be true across the board anymore. A reader who takes the ERC-20 → native exception at face value has no way to tell whether the fee-sponsorship requirement at :37 still applies to them. Scope that warning, or add the one clause that resolves it.

Fix this →

4. The decision tree still walks readers into the caveat

gasless-swaps.mdx:22, unchanged across both commits. The page's own intro calls this tree the entry point ("We've put together a decision tree below to help you arrive at the solution that best fits your application"), and it still sends every BYO-wallet reader to Permit-based Gasless with _Limitation: not all ERC-20s support permit_ as the sole caveat. A same-chain reader following the tree as instructed lands on the flow this PR says doesn't work, and only learns otherwise if they read past the node they clicked. Extending the node label is a one-line fix.

5. Scope — the /execute disambiguation is still not there

The description's second clause ("distinguish the Gasless Swaps page from the Gasless Execution (/execute) page") remains unimplemented. Verified: features/gasless-swaps.mdx links to /references/api/execute twice (:75, :146) but never to /features/gasless-execution; features/gasless-execution.mdx never mentions Gasless Swaps. They sit two entries apart in docs.json (:47, :49) with near-identical names — the exact confusion the description targets. An earlier round of this PR apparently touched gasless-execution.mdx; the current diff doesn't. Deferred deliberately, or lost in the rewrite? Worth updating the description either way.

6. Style (AGENTS.md)

• §2.5 / §2.10 — the merged callout now carries four distinct claims in four sentences (USDC is gasless / other ERC-20s need approval / same-chain ERC-20 → ERC-20 is limited / ERC-20 → native is the exception). Merging fixed the stacking, but §2.5 scopes callouts to "quick pointers" and §2.10 caps paragraphs at 2–3 sentences. A short <Warning> for the token-approval fact plus a ### Same-chain swaps subsection under Permit-based Gasless would carry the route-shape matrix better than one dense callout — and would give step-execution.mdx:245 a more specific anchor than #permit-based-gasless.
• §2.7 — step-execution.mdx:245 is now the longest cell in that table by a wide margin (two sentences plus an inline cross-link), against "keep cell descriptions concise; move long explanations into prose below the table." The ### authorize2 section right below is where the second sentence belongs — and it's already there, so the table cell can just say "Same-chain permits — see below."
• Nit: ERC-20 is now correctly consistent throughout gasless-swaps.mdx, but this PR introduced the hyphenated spelling into step-execution.mdx (:245, :479), where the surrounding lines still use ERC20 (:234, :255, :299). AGENTS.md §5 doesn't rule on it; flagging only for within-page consistency.

---

Verification note: no network egress from this runner, so I could not check https://api.relay.link/documentation/json. Findings 1 and 2 lean on the live-quote artifacts Greptile posted on this PR rather than my own API calls — worth confirming against the solver before acting on them. Everything else is verified against the repo. Repo has no MDX linter or test suite wired up, so nothing was run beyond reading and grepping.

Summary: #1 blocks — the current wording states as impossible something a live test on this PR showed working, and it removed the qualifier that used to leave room for it. #2 is close behind: the reconciliation may have picked the wrong step id, and same-chain authorize1 is documented nowhere. #3–#4 are internal inconsistencies this PR's new text creates or leaves standing. #5 is a scope gap against the description. #6 is style.

No changes were made — this was a review-only request.
· pedro/int2-266-clarify-same-chain-gasless-swap-limitations

[mintlify]

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

Project	Status	Preview	Updated
unevenlabs	🟢 Ready	View Preview	Sep 9, 2026, 6:57 PM

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