docs: split Pay with Exchange & Self-custodial wallets into separate pages

[devin-ai-integration]

Description

Splits the combined "Pay with Exchange & Self-Custodial Wallets" page into two dedicated pages:

• Pay with Exchange — retains all CEX-related content (Binance, Coinbase flows, exchange FAQs, strategic benefits)
• Pay with Self-Custodial Wallets — new page following the same structure, populated with content from the original self-custodial wallet FAQs and strategic benefits sections, plus a new intro/feature summary derived from that FAQ content

Changes:

• appkit/payments/pay-with-exchange.mdx — removed self-custodial wallet FAQs section; updated title and descriptions to be exchange-only; removed "early access" section (feature is now released)
• appkit/payments/pay-with-self-custodial-wallets.mdx — new page with intro, demo link, get started cards, and all wallet FAQs (User Experience, Compliance, Integration, Pricing, Strategic Benefits)
• appkit/payments/overview.mdx — updated to list both pages separately in the "How Reown Solves These Problems" section and added a separate card for self-custodial wallets
• docs.json — added pay-with-self-custodial-wallets to sidebar navigation for all 5 sections (overview, React, Next.js, Vue, JavaScript)
• Created framework-specific stub pages for React, Next.js, Vue, and JavaScript under payments/pay-with-self-custodial-wallets.mdx
• snippets/appkit/shared/appkit-pay-wallet-react.mdx — new shared snippet for wallet framework stubs, with wallet-focused intro, no exchange-specific hooks/sections, and usePay hook documentation
• appkit/javascript/payments/pay-with-self-custodial-wallets.mdx — standalone JS wallet page with exchange-specific content removed (getExchanges function, exchange-specific network text)

Updates since last revision

• Removed "Interested in getting early access?" sections from both pages, as both features are now fully released
• Fixed "Get Started" card links on the self-custodial wallets page to correctly point to /appkit/{framework}/payments/pay-with-self-custodial-wallets
• Created a dedicated appkit-pay-wallet-react.mdx snippet so React/Next/Vue wallet stubs no longer render exchange-focused content
• Removed getExchanges from the JS self-custodial page functions list (exchange-only)
• Fixed typo: "connected another" → "connect another" in wallet FAQ

⚠️ Items for human reviewer:

1. The new wallet snippet (appkit-pay-wallet-react.mdx) documents a usePay hook in the Hooks section — please verify this is the correct/complete hook API for self-custodial wallet flows.
2. Both wallet and exchange pages reference the same @reown/appkit-pay npm package — confirm this is correct since both features share the SDK.

Link to Devin run: https://app.devin.ai/sessions/55ed845aeae644068683a3d7966c07bb
Requested by: Jem Conlon (jem@walletconnect.com)

Tests

• Ran the changes locally with Mintlify and confirmed that the changes appear as expected.
• Ran a grammar check on the updated/created content using ChatGPT.

Direct link to the deployed preview files

• Pay with Exchange
• Pay with Self-Custodial Wallets
• Payments Overview

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[claude]

Claude finished @devin-ai-integration[bot]'s task in 2m 14s —— View job

---

🤖 Claude Code Review

• Gathering context
• Reading tone of voice guidelines
• Reviewing changed files
• Running data classification check
• Compiling findings

Found 4 issue(s)

Issue 1: Broken "Get Started" card links on self-custodial wallets page

ID: pay-self-custodial-broken-links-a3f1
File: appkit/payments/pay-with-self-custodial-wallets.mdx:43-65
Severity: HIGH
Category: breaking_change

Context:

• Pattern: All four framework cards link to /appkit/{framework}/payments/pay-with-exchange instead of the new self-custodial wallet pages
• Risk: Users clicking "Get Started" from the self-custodial wallets page will land on exchange integration docs, causing confusion and misdirection
• Impact: Broken navigation for all four framework paths (React, Next.js, Vue, JavaScript)
• Trigger: Any user clicking the "Get Started" cards on the new page

Recommendation:

<Card icon="react" href="/appkit/react/payments/pay-with-self-custodial-wallets">
<Card icon="square-n" href="/appkit/next/payments/pay-with-self-custodial-wallets">
<Card icon="vuejs" href="/appkit/vue/payments/pay-with-self-custodial-wallets">
<Card icon="js" href="/appkit/javascript/payments/pay-with-self-custodial-wallets">

Fix this →

---

Issue 2: Exchange-specific content on JavaScript self-custodial wallets page

ID: js-self-custodial-exchange-content-b7c2
File: appkit/javascript/payments/pay-with-self-custodial-wallets.mdx:88,123-126
Severity: HIGH
Category: code_quality

Context:

• Pattern: Line 88 links to exchange-specific networks/assets ("across different exchanges (Coinbase, Binance)") and lists getExchanges function (line 123-126) — both are exchange-only concepts
• Risk: Developers building self-custodial wallet integrations will be misled into thinking they need exchange configuration or that getExchanges is relevant to their use case
• Impact: Inaccurate documentation; the JS self-custodial page is functionally identical to the exchange page (only the intro text differs)
• Trigger: Any developer reading the JavaScript integration guide for self-custodial wallets

Recommendation:

• Line 88: Replace with a general "Supported Networks and Assets" statement not tied to exchange networks
• Lines 123-126: Remove getExchanges from the functions list on the self-custodial page; it is exchange-only

---

Issue 3: React/Vue/Next.js stubs import exchange-focused snippet

ID: framework-stubs-exchange-snippet-c4d3
File: appkit/react/payments/pay-with-self-custodial-wallets.mdx:6, appkit/vue/payments/pay-with-self-custodial-wallets.mdx:6, appkit/next/payments/pay-with-self-custodial-wallets.mdx:6
Severity: MEDIUM
Category: code_quality

Context:

• Pattern: All three framework stubs import appkit-pay-react.mdx which begins with "AppKit Pay with Exchange unlocks a powerful new flow: users can pay in crypto directly from their Centralized Exchange (CEXs) accounts", and contains exchange-only hooks (useAvailableExchanges, usePayUrlActions, useExchangeBuyStatus) and "Test the complete exchange flow" section
• Risk: Self-custodial wallet pages will render exchange-specific content, contradicting the page title and misleading developers
• Impact: All three framework pages for self-custodial wallets will describe the exchange flow, not the wallet flow
• Trigger: Any developer following React/Vue/Next.js integration docs for self-custodial wallets

Recommendation: Either create a separate appkit-pay-wallet.mdx snippet, or add a parameter/flag to the shared snippet to conditionally render wallet vs. exchange content. This was flagged as item #2 in the PR description and needs a decision before merging.

---

Issue 4: Typo in self-custodial wallets FAQ

ID: pay-self-custodial-typo-e5f4
File: appkit/payments/pay-with-self-custodial-wallets.mdx:96
Severity: LOW
Category: code_quality

Context:

• Pattern: "a user can simply disconnect a wallet and connected another"
• Risk: Grammatical error in user-facing docs
• Impact: Minor readability issue

Recommendation: Change "connected" → "connect": a user can simply disconnect a wallet and connect another without losing the payment detail.

Fix this →

Data classification: ✅ No issues found (all content is public-tier documentation)

Tone of voice: ✅ Content is appropriately professional, informative, and aligned with Reown's voice guidelines. No violations found.

Note: Issues 2 & 3 correspond to items #2 and #3 flagged in the PR description — these require a deliberate decision on whether to share or separate the integration content before merging.

[github-actions]

🤖 Auto Review Issue: Broken "Get Started" card links on self-custodial wallets page

Severity: HIGH
Category: breaking_change
Tool: Claude Auto Review

Context:

• Pattern: All four framework cards link to /appkit/{framework}/payments/pay-with-exchange instead of the new self-custodial wallet pages
• Risk: Users clicking "Get Started" from the self-custodial wallets page will land on exchange integration docs, causing confusion and misdirection
• Impact: Broken navigation for all four framework paths (React, Next.js, Vue, JavaScript)
• Trigger: Any user clicking the "Get Started" cards on the new page

Recommendation:

<Card icon="react" href="/appkit/react/payments/pay-with-self-custodial-wallets">
<Card icon="square-n" href="/appkit/next/payments/pay-with-self-custodial-wallets">
<Card icon="vuejs" href="/appkit/vue/payments/pay-with-self-custodial-wallets">
<Card icon="js" href="/appkit/javascript/payments/pay-with-self-custodial-wallets">

Fix this →

[github-actions]

🤖 Auto Review Issue: Exchange-specific content on JavaScript self-custodial wallets page

Severity: HIGH
Category: code_quality
Tool: Claude Auto Review

Context:

• Pattern: Line 88 links to exchange-specific networks/assets ("across different exchanges (Coinbase, Binance)") and lists getExchanges function (line 123-126) — both are exchange-only concepts
• Risk: Developers building self-custodial wallet integrations will be misled into thinking they need exchange configuration or that getExchanges is relevant to their use case
• Impact: Inaccurate documentation; the JS self-custodial page is functionally identical to the exchange page (only the intro text differs)
• Trigger: Any developer reading the JavaScript integration guide for self-custodial wallets

Recommendation: - Line 88: Replace with a general "Supported Networks and Assets" statement not tied to exchange networks

• Lines 123-126: Remove getExchanges from the functions list on the self-custodial page; it is exchange-only

[github-actions]

🤖 Auto Review Issue: React/Vue/Next.js stubs import exchange-focused snippet

Severity: MEDIUM
Category: code_quality
Tool: Claude Auto Review

Context:

• Pattern: All three framework stubs import appkit-pay-react.mdx which begins with "AppKit Pay with Exchange unlocks a powerful new flow: users can pay in crypto directly from their Centralized Exchange (CEXs) accounts", and contains exchange-only hooks (useAvailableExchanges, usePayUrlActions, useExchangeBuyStatus) and "Test the complete exchange flow" section
• Risk: Self-custodial wallet pages will render exchange-specific content, contradicting the page title and misleading developers
• Impact: All three framework pages for self-custodial wallets will describe the exchange flow, not the wallet flow
• Trigger: Any developer following React/Vue/Next.js integration docs for self-custodial wallets

Recommendation: Either create a separate appkit-pay-wallet.mdx snippet, or add a parameter/flag to the shared snippet to conditionally render wallet vs. exchange content. This was flagged as item #2 in the PR description and needs a decision before merging.

[github-actions]

🤖 Auto Review Issue: Typo in self-custodial wallets FAQ

Severity: LOW
Category: code_quality
Tool: Claude Auto Review

Context:

• Pattern: "a user can simply disconnect a wallet and connected another"
• Risk: Grammatical error in user-facing docs
• Impact: Minor readability issue

Recommendation: Change "connected" → "connect": a user can simply disconnect a wallet and connect another without losing the payment detail.

Fix this →

[0xmkh]

Where is this coming from? <AppKitPayWallet /> doesnt' exist

[devin-ai-integration]

<AppKitPayWallet /> is the MDX component rendered from the import on line 6:

import AppKitPayWallet from "/snippets/appkit/shared/appkit-pay-wallet-react.mdx";

This follows the same pattern used by the existing exchange pages — e.g., in appkit/react/payments/pay-with-exchange.mdx:

import AppKitPay from "/snippets/appkit/shared/appkit-pay-react.mdx";

<AppKitPay />

The actual snippet content lives at snippets/appkit/shared/appkit-pay-wallet-react.mdx (created in this PR) — it's a wallet-focused version of appkit-pay-react.mdx with exchange-specific content removed.