docs(drift): draft from internal source

[pedromcunha]

Drafted from an internal source repo, requested by @ipeleg.

This PR was auto-generated by the reusable-docs-draft-pr workflow from a Claude-drafted update in the source repo. It is opened as a draft — please review, edit as needed, and mark ready for review before merging.

Review checklist

• Content matches the behavior shipped in the source PR
• No internal-only details (service names, file paths, unreleased names, security internals) leaked into the draft
• Conforms to CLAUDE.md style rules
• Cross-references and internal links resolve
• Any Needs human input items from the source comment are addressed

---

Generated by reusable-docs-draft-pr.yml in relayprotocol/agents-config.

[github-actions]

Claude finished @ipeleg's task in 2m 1s —— View job

---

Review: docs(drift): draft from internal source (#384)

• Gather context (diff, changelog page, style guide)
• Check conformance with AGENTS.md rules (§4.5 changelog format, §2 global rules, §5 terminology)
• Verify cross-references and internal links resolve
• Check for internal-only detail leakage
• Post review

The entry is well-placed (newest-first ordering is correct, date matches today, frontmatter untouched) and the **Behavior change** lead matches established practice on this page. One substantive issue and a few style nits.

---

🔴 Companion page not updated — docs now contradict each other

AGENTS.md §4.4 says a behavior change that alters observable output should update the relevant page's prose and add a changelog entry. This PR only did the changelog half. references/api/api_guides/migrating-to-requests-v3.mdx still documents the old blanket fallback in three places:

Line	Current text	Problem
:376	"actual falls back to quoted when there's no execution data yet"	Now only true per-side — origin no longer falls back on no-fill rows
:473	data.route.actual … "falls back to quoted"	Same claim in the "Added in v3" table
:490	"fall back to origin.outputCurrency for same-chain swaps"	Actively misleading now

Line 490 is the concrete hazard. The migration checklist tells same-chain-swap integrators to read the received amount from route.actual.origin.outputCurrency. Under the new behavior that field is null on rows where a deposit was observed but no fill occurred — so an integrator who follows the checklist verbatim goes from reading a (wrong-but-present) quoted amount to reading null. That's the same class of silent breakage this changelog entry exists to surface, and it's currently undocumented on the page people actually read while integrating.

Suggest updating all three to describe the fallback as per-side, and adding a sentence to the checklist step noting the null case.

Fix this →

---

🟡 Style nits

1. on-chain → onchain — references/api/changelog.mdx:8. §5 is explicit: "onchain — one word, no hyphen." The repo is 65 onchain vs 12 on-chain, so the guide's rule is the dominant convention and the new line adds to the drift.

Fix this →

2. Paragraph length — §2.10 caps paragraphs at 2–3 sentences; this entry is one ~5-line, 4-sentence block. It's the densest entry on the page. Splitting after the outputCurrency/destination sentence (new behavior ¶, then previous behavior + scope ¶) would read better without losing anything.

3. "fails before solve" — "solve" as a verb reads as internal jargon; §5 only establishes solver as a noun. …that fails before a fill is attempted says the same thing in the docs' vocabulary. (Otherwise the leak check is clean — no service names, file paths, or internal identifiers.)

4. No outbound link — every other multi-clause entry on this page links to the page carrying the full explanation. Worth pointing at the migration guide, since that's where route.{quoted,actual} semantics are documented. Note there is no GET /requests/v3 endpoint reference page in references/api/, so the migration guide is the only link target.

---

✅ Verified

• Ordering (newest-first), date, and ## heading form match §4.5.
• Field paths (data.route.actual.origin.inputCurrency, .outputCurrency, data.route.quoted.destination) match the shapes documented in migrating-to-requests-v3.mdx.
• No frontmatter or nav changes needed.

⚠️ Can't verify from this repo

The claims that actual.destination continues to fall back to quoted.destination, and that actual.origin.outputCurrency is null (rather than absent/omitted) — worth confirming against the source PR, since null vs. omitted changes how integrators guard the read.

_{Drive-by, pre-existing and outside this diff: references/api/changelog.mdx:30-31 is missing a blank line between the v2-deprecation entry and the ## 2026-07-09 heading.}

--- · Branch docs-drift/src-eaeae550b8-b472e8b

[mintlify]

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

Project	Status	Preview	Updated (UTC)
unevenlabs	🟢 Ready	View Preview	Jul 30, 2026, 5:38 PM

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