docs(positioning): separate Relay platform and protocol

[jmaier6]

No description provided.

[mintlify]

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

Project	Status	Preview	Updated
unevenlabs	🟢 Ready	View Preview	Sep 11, 2026, 6:16 PM

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

[github-actions]

Claude finished @jmaier6's task in 8m 57s —— View job

---

Code review — docs(positioning): separate Relay platform and protocol

• Gather context (48 files, 1 commit, docs/platform-protocol-positioning)
• Verify link integrity, deletions/redirects, nav wiring
• Check §1.2 / §5 positioning-policy compliance against the diff
• Post findings

The split of Relay platform vs Relay Protocol vs solvers is applied consistently across the 48 files, and the mechanical parts hold up. Verified clean:

• Every internal link added in the diff resolves to an existing .mdx; the #status-lifecycle, #refunds, and #oracle anchors referenced from other pages still exist.
• No remaining inbound links to the two deleted pages (references/protocol/guides/for-solvers.mdx, resources/understanding-relay.mdx) or the deleted images/status-lifecycle.png. Both deletions have docs.json redirects, and neither redirect chains into another redirect source.
• Banned terms Relay Network, the Relay Solver, our solver, payments network are now absent repo-wide.
• Two previously broken smart_accounts/smart-accounts links and one link to the retired /how-it-works/the-relay-solver page were fixed in passing.
• The protocol.v2 reshape in for-apps.mdx matches the field names in input-validation.mdx; the stray # Wallet Detection H1 removal and the "transfer to the Depository" correction are consistent with for-apps.mdx:122 and references/protocol/how-it-works.mdx:84.
• script.js / style.css don't key off the renamed first tab label.

Seven findings, roughly most-severe first.

---

1. contract-addresses.mdx:8 contradicts AppBalance.mdx in the same PR

references/api/api_resources/contract-addresses.mdx:8 adds a blanket instruction:

Always use the transaction targets returned by your quote rather than sending funds to an address from this reference.

But snippets/AppBalance.mdx — edited in this same PR — instructs readers to transfer to 0xf70da97812cb96acdf810712aa562db8dfa3dbef, which is the EVM solver address listed on contract-addresses.mdx:23. AGENTS.md §1.2 explicitly allows the app-balance exception ("If an integration actually uses a direct transfer (for example app-balance funding), state that exception accurately"), so the fix is to name it here rather than issue an absolute rule. Fix this →

2. step-execution.mdx — caveat added to one deposit example but not the other

The ### deposit example at references/api/api_core_concepts/step-execution.mdx:269 gained "The following historical response illustrates the step shape, not an address to reuse for new deposits." The Full Quote Example at line ~579 still shows "to": "0xf70da978…" (the solver EOA) plus the legacy "description": "Deposit funds for executing the calls", with no equivalent caveat. A reader who scrolls to the full example sees exactly the pattern the earlier caveat warns against. Fix this →

3. index.mdx:17 — landing page no longer links Quickstart

The Quickstart card was replaced by "What is Relay?", and the three cards now point at /what-is-relay, /references/api/overview, /references/protocol/overview. Quickstart survives only inside the API Reference tab (docs.json:82); it isn't in the renamed tab's Introduction group either. AGENTS.md §3.7 calls references/api/quickstart.mdx the single "you are here" entry point, so losing its landing-page link is a real regression in the entry path — worth either keeping a fourth card or linking it from /references/api/overview's lead. Fix this →

4. for-apps.mdx:34 — two incompatible chainId formats on one page

The new protocol.v2 example gives "chainId": "optimism" inside paymentDetails, and the field list calls it "the protocol chain ID". Further down, the same page's worked Oracle derivation uses chainId = "42161" (references/protocol/guides/for-apps.mdx:117). One of these is wrong, or they're different fields that need distinguishing — as written a reader building the Hub order address can't tell which format to hash. Worth confirming against the live API response before merge. Fix this →

5. features/gasless-swaps.mdx:42 — role blurring and a dropped mechanic

The permit section now reads "Solvers execute the authorized flow and pay transaction gas," while the ERC-4337 section three sections down says "a relayer broadcasts the transaction and pays gas" (features/gasless-swaps.mdx:75). AGENTS.md §5 keeps solver (liquidity) and relayer (broadcasting) distinct — attributing gas payment to solvers in one flow and a relayer in the other reads as a contradiction rather than a deliberate difference. It also sits awkwardly next to line 67's "The user still needs to pay for the origin gas fee."

Separately, the Fulfillment step lost the concrete mechanic: "withdraws tokens from the user's EOA" → "The signed permit authorizes the token transfer." The rewrite is more neutral but strictly less informative about what the permit actually authorizes. Fix this →

6. AGENTS.md:325 — stale tab list after the rename

§4.6 still says the Changelog tab sits "alongside Overview, API Reference, RelayKit, and Relay Protocol," but this PR renamed that first tab to Relay Platform (docs.json:15). Small, but it's the guide that automation reads. Fix this →

7. refunds.mdx:44 — heading now half-unanswered

The section is still titled "Are refunds automatic & instant?" but the rewrite dropped "almost instantly" without putting any timing statement in its place; the new text covers only the automatic half. No timing claim remains anywhere on the page. If the old "almost instantly" was the overclaim being removed (reasonable under §1.2's "zero-latency guarantees" rule), the heading should drop & instant too, or the body should say something bounded about timing. Fix this →

---

Findings 1, 2, and 4 are the ones I'd want resolved before merge — the first two are actively contradictory instructions about where to send funds, and the third could send an integrator down the wrong hashing path. Nothing else here is blocking.
· Branch: docs/platform-protocol-positioning

[greptile-apps]

Confidence Score: 3/5

Not safe to merge until the Quickstart accurately identifies the transaction target.

Findings

1.   Solver EOA called Depository ▶

Summary

• This update reorganizes Relay documentation around the Platform and Protocol, refreshes integration guidance, and adds the withdrawal-balance endpoint to navigation. The Quickstart still incorrectly describes a solver EOA as the Relay Depository contract, which can lead integrations to misunderstand the destination of a quoted transaction.

_{Reviews (2) · Last reviewed commit: "Merge branch 'main' into docs/platform-p..."}

[pedromcunha]

Same comment here, this is actually a part of the api response

[pedromcunha]

Sounding like a broken record but also the same issue here re actual api response data shape

[github-actions]

Claude encountered an error after 1m 52s —— View job

---

Code review — docs(positioning): separate Relay platform and protocol

Reviewing the new commit and re-checking prior findings.

• Gather context (48 files, 2 commits)
• Review the diff for correctness and style-guide compliance
• Re-check the seven findings from the earlier review
• Post findings
  · Branch: docs/platform-protocol-positioning

[github-actions]

Claude encountered an error after 9m 21s —— View job

---

I'll analyze this and get back to you.