Add deposit address marketing intro

[scout-relayprotocol]

Summary

• add the approved deposit-address positioning and bottom-of-funnel value proposition to the top of the feature page
• explain Open vs Strict modes, the user flow, audiences, benefits, and limitations before the existing integration guide
• keep all existing technical documentation intact and link related fee sponsorship and price stabilization features

Validation

• git diff --check
• verified frontmatter, code fences, and MDX component tags are balanced

Notes

• ships without the planned How it works diagram tracked separately in MAR-1407

Linear: https://linear.app/relayprotocol/issue/MAR-1395/deposit-addresses

[mintlify]

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

Project	Status	Preview	Updated (UTC)
unevenlabs	🟢 Ready	View Preview	Jul 31, 2026, 11:07 AM

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

[github-actions]

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

---

Code review: deposit address marketing intro

• Read PR diff and full page
• Check AGENTS.md style-guide compliance (§2, §3.1)
• Verify internal links resolve
• Check terminology and voice consistency
• Post review

The positioning content itself is strong and the technical section below is untouched as claimed. My concerns are that a few of the new claims contradict the technical documentation further down the same page — in ways that could cause an integrator to lose funds — plus some structural duplication and style-guide drift.

---

Blocking: new claims contradict the technical section

1. features/deposit-addresses.mdx:42 — "A wrong amount or a failed fill refunds automatically" is not true unconditionally

This is stated as an unqualified user guarantee, but the technical section on this same page says the opposite in four places:

• L99 / L986: "Omitting refundTo disables automatic refund — there is no internal fallback."
• L929: a too-small deposit "is refunded to the refundTo address (if set)."
• L985: if the depositor is detected as a CEX address, "Relay aborts auto-refund and requires manual refund / recovery instead."
• L969: wrong currency (non-solver token) is "Not supported and not currently recoverable."

The contradiction is sharpest for the exact audience the intro leads with (L10: "a customer paying from a centralized exchange"), where L990 explicitly warns against relying on auto-refund to the depositor. An integrator who reads only the marketing intro can reasonably ship without refundTo and silently have no refund path.

Suggested: **Safe by default.** With refundTo configured, a wrong amount or a failed fill refunds automatically. — plus a pointer to Refund Behavior.

Fix this →

2. features/deposit-addresses.mdx:59 — Limitations understates a non-recoverable-funds risk

Long-tail tokens with unknown liquidity can't be sent to a deposit address (a negligible share of volume).

They can be sent — that's the whole hazard. L1413 carries a <Warning>: "Non-solver tokens and NFTs sent to deposit addresses are not recoverable through normal processes." "Limitations" is exactly where a reader goes looking for this, and framing an unrecoverable-loss case as a coverage gap plus "a negligible share of volume" is a meaningful softening. Recommend stating that non-solver tokens sent to a deposit address are not recoverable, and linking to Supported Currencies.

Fix this →

3. features/deposit-addresses.mdx:46 — the "$5 checkout" example works against the Gas Overhead caveat

L1393–1400 says deposit addresses add ~33,000 gas (native) to ~70,000 gas (ERC-20) of sweep overhead, and "For very small amounts, the gas overhead may make deposit addresses less cost-effective than direct calldata execution." A $5 checkout is the case the caveat is warning about. Either raise the figure or drop the specific dollar amount.

4. features/deposit-addresses.mdx:24 and :12 — "non-custodial escrow" / "funds stay theirs until the order fills"

The technical flow (L69) says Relay "detects the deposit onchain and sweeps funds to the depository contract" before the fill, and L985 confirms the depository holds them. The claim isn't wrong in spirit, but the marketing wording invents a term ("non-custodial escrow") that appears nowhere else in these docs. Recommend matching the established vocabulary and linking to the Depository Contract — §5 asks for that link on first mention.

5. features/deposit-addresses.mdx:22 — step 1 omits the required parameter

"Request an address via the API with your destination chain, output asset, and trade type" leaves out useDepositAddress: true, which is the thing that actually makes it a deposit address (L67, L76), and refundTo, which is required for Strict (L106, L916). The 4-step summary and the technical 4-step list should not disagree on what the request contains.

---

Structure

6. Duplicated sections that will drift apart. The PR adds sections that overlap existing ones without consolidating:

New	Already on page
## Open and Strict (L16)	## Open vs Strict Deposit Addresses (L91) + ### Address Reuse (L85) + ### Comparison table (L110)
## How it works (L20)	## Technical integration (L65), which is the renamed ## How It Works

Two 4-step flow lists and two Open-vs-Strict explanations, ~75 lines apart, both in the page TOC. The new mode summary at L18 is already thinner than the ### Comparison table and will fall out of sync with it. Suggest cutting L16–18 down to one or two sentences that link to #open-vs-strict-deposit-addresses rather than restating the rules.

7. §3.1's required definitional intro was removed. The profile states the one strictly required element is an intro paragraph using "<FeatureName> is a feature that …" or similar definitional framing. The deleted paragraph was that, and was also the only place near the top explaining what a deposit address is and naming useDepositAddress: true. A reader arriving cold now gets ~50 lines of positioning before any definition. Recommend keeping a one-paragraph definitional lead and putting the positioning immediately after it.

8. Marketing-first content on a features/ page cuts against the §3.1/§3.2 split. §3.1 says feature guides are "practical, task-oriented"; §3.2 reserves "positioning-first, marketing-adjacent" for use-case guides. More concretely, ## Who it's for (L44–51) restates pages that already exist and are not linked:

• solutions/payment-service-providers.mdx
• solutions/wallets-and-wallet-providers.mdx
• solutions/commerce-and-payments.mdx

§2.6 asks for a link on first mention of a concept that has its own page. At minimum link out; ideally the audience positioning lives in solutions/ and this page links to it.

---

Style-guide details

• §2.10 paragraph length (2–3 sentences max): L10 (4 sentences), L12 (4, and very long), L18 (6 sentences in one block), and the L46–49 bullets (3–4 each) all exceed it. L55 ## What you get is a single run-on sentence listing four items — should be a bullet list.
• §2.9 bold usage: the L8 tagline is bold prose; bold is reserved for parameter names, values the reader types, and UI element names.
• Heading case: the new headings are sentence case (How it works, Why it matters, Who it's for, What you get, Technical integration) while every existing heading on the page is Title Case (Key Parameters, Address Reuse, Quote Regeneration, Refund Behavior, Caveats). Pick one per page.
• §5 terminology: crosschain (L47, L55) should be cross-chain, and same chain (L12, L23, L55) should be same-chain. Note the repo has drifted here — solutions/ and references/protocol/ use crosschain — so this may be worth resolving in AGENTS.md rather than in this PR.
• §2.6 missing links: "85+ chains" (L12, L35) is plain text here; the three solutions/ pages all link it to /references/api/api_resources/supported-chains. "Compliance screening on arrival" (L55) should link /security/compliance — the claim itself checks out against solutions/payment-service-providers.mdx:24. "see the integration guide below" (L18, L59) should be an anchor link to #technical-integration.
• Anchor change: renaming ## How It Works → ## Technical integration while adding a new ## How it works means /features/deposit-addresses#how-it-works now lands on the marketing section instead of the technical steps. Nothing in this repo links to that anchor, but external/marketing links may.
• L14 uses typographic quotes (“We can't take that”); it's the only instance in features/.
• §2.4 tone ("clear, Stripe-adjacent prose"): "kill conversion", "is scary", "becomes captured volume", "the wedge that serves your entire book" read as sales copy. "a pattern that has repeatedly proven risky" (L10) is an unsourced risk claim — either ground it or cut it.

---

Verified as fine

• Frontmatter unchanged and valid; <CodeGroup> / callout tags balanced; no fence imbalance.
• /features/fee-sponsorship and /features/price-stabilization (L61) both exist.
• Root-relative link style per §2.6.
• Nav entry features/deposit-addresses in docs.json:45 needs no change.
• --- at L63 is permitted on feature guides (§2.5).
• The Open/Strict summary at L18 matches the detailed behavior at L119 and L951–953 (overpayment fills quoted amount and refunds excess; underpayment refunds).

No changes pushed — this is review feedback only. Findings 1 and 2 are the ones I'd want resolved before merge; the rest are judgment calls for you.
· branch scout/MAR-1395-deposit-address-marketing