Skip to content

Payments homepage/security page + full docs.walletconnect.network migration under /wallets, /apps, /network - #106

Open
juanisierra wants to merge 24 commits into
mainfrom
network-docs-migration
Open

Payments homepage/security page + full docs.walletconnect.network migration under /wallets, /apps, /network#106
juanisierra wants to merge 24 commits into
mainfrom
network-docs-migration

Conversation

@juanisierra

@juanisierra juanisierra commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR bundles two rounds of work: the initial Payments/Network/Security page additions and API Reference migration (docs-update), followed by the full migration of the Wallets SDK, Apps SDK, and Network/tokenomics content from docs.walletconnect.network into this repo (network-docs-migration).

Part 1 — Payments, security, API Reference (from docs-update)

  • payments/index.mdx — new WalletConnect Pay homepage at /payments
  • security.mdx — new page at /security covering SOC2 Type II, audits, and the bug bounty program (not yet linked from anywhere — flagging again since it's still true)
  • index.mdx — reworked root homepage into a general WalletConnect ecosystem quickstart (Wallets/Apps/Payments/Network cards)
  • API Reference migration: /api-reference → /payments/api-reference — moved all 51 files, updated docs.json nav/redirects, the generate-specs.mjs CI generator, and 10 content files with inline links

Part 2 — Wallets/Apps/Network migration from docs.walletconnect.network (network-docs-migration)

Migrated the entire docs.walletconnect.network Mintlify site (source: a local checkout of the foundation docs repo) into this repo, combining the .network and .com domains:

  • /wallets — Wallet SDK docs: Web, Android, iOS, Flutter, React Native, .NET, Chain Support, WalletGuide, Custodians, Guides, and a new consolidated "More" section (Best Practices, Staying up to date, Web3Wallet→WalletKit migration guides)
  • /apps — App SDK docs: React, Next.js, Vue, JavaScript
  • /network — Network/tokenomics docs: landing page, Service Nodes, Participants (Service Nodes + Wallets), and a consolidated WCT Token section (overview, rewards, service-node-rewards, staking, governance, contracts, faq)
  • 209 total nav pages, all verified to resolve to real files; supporting images and snippets copied over
  • wallets/ and apps/ sit at the top level (not nested under /network), matching the authoritative migration spreadsheet's actual URL column, after an earlier attempt nested them under /network and was corrected
  • Extensive redirects from the old docs.walletconnect.network paths (/wallet-sdk/**, /app-sdk/**, /walletguide/**, /custodians/**, /guides/**, /token-dynamics/**, /wct-staking/**, /governance, /contracts, etc.) to their new homes, including specific overrides for pages that were renamed along the way (e.g. staying-up-to-date → updating-wallet-sdk, the web3wallet-migration/ restructure, WalletGuide's submit-wallet/explorer-api/submit-chain renames)
  • navigation.global.anchors (WalletConnect/Blog/Whitepaper/Specs/Report an Issue sidebar row) restored, and report-an-issue.mdx migrated as a site-wide utility page
  • Nav order, group labels, and sidebar titles cross-checked against the migration spreadsheet's sidebar-structure reference table (WalletGuide/WCT Token ordering, "Custodians & Institutions" label, several sidebarTitle overrides)

Missing items / follow-ups

  • /security still has no inbound link from anywhere in the site
  • security.mdx has three unresolved links (audit report, 3× "View Report" table cells, bug bounty disclosure form) pending real URLs
  • docs.json's top-level name/description still say "WalletConnect Pay Docs" — stale now that the site covers Wallets/Apps/Network too
  • 21 pre-existing orphaned pages inherited from the source repo's own nav gaps (mostly Android/iOS/React Native notification pages) — not linked from any nav, not something introduced by this migration

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe

juanisierra and others added 13 commits September 4, 2026 11:02
@juanisierra @claude
docs: add WalletConnect Pay homepage at /payments
fd53a98 
New landing frame page mirroring the root homepage, scoped to Pay:
product cards for Wallets, PSPs, Ecommerce, and Merchant Dashboard.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: add security information page
c5971e1 
Standalone page at /security covering SOC2 Type II certification,
the wallet SDK's Trail of Bits audit, third-party audit history, and
the bug bounty disclosure process. Not wired into sidebar nav, same
pattern as license-update.mdx.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: add Network section overview page
a2b9ce9 
Adds /network with an overview of the WalletConnect Network's
technology, permissioned architecture, and participants. Not yet
wired into sidebar nav; links to /network/governance and
/network/WCT-token, which don't exist in this repo yet.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: update homepage to link out to Wallets, Apps, Payments, Network
086d8e4 
Replaces the WalletConnect Pay-specific homepage with a general
WalletConnect ecosystem quickstart linking to Wallets, Apps, Payments,
and the Network. /wallets and /apps don't exist in this repo yet.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: migrate /api-reference to /payments/api-reference
4624d0d 
Repoints docs.json nav, inline links across payments docs, the
generate-specs.mjs generator, and the update-specs CI workflow to the
new location. Adds a catch-all redirect from the old /api-reference/*
paths so existing bookmarks and search results keep working.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: remove /network overview page
72e38ee 
Content will be added elsewhere; homepage still links to /network,
which will 404 until that's back.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: migrate Wallets/Apps/Network docs from docs.walletconnect.netwo…
ddf8e8a 
…rk under /network

Migrates the full content of the docs.walletconnect.network Mintlify
site (github.com/WalletConnect/... foundation docs repo) into this
repo, nested under a /network prefix, combining the .network and .com
domains into one site:

- wallets/ -> network/wallets/ (Wallet SDK docs: Web, Android, iOS,
  Flutter, React Native, .NET, chains, custodians, walletguide,
  guides, features, more) — 116 files
- apps/ -> network/apps/ (App SDK docs: React, Next, Vue, JavaScript)
- WCT-token/ -> network/WCT-token/ (overview, rewards,
  service-node-rewards, staking, faq, governance, contracts — already
  consolidated in the source repo)
- service-nodes.mdx -> network/service-nodes.mdx
- network/wallets.mdx (network participant page, distinct from the
  Wallet SDK docs) carried over as-is
- network/index.mdx: new /network landing page, using network.mdx's
  content (Technology/Permissioned Network/Participants) as the
  canonical version; overview.mdx's shorter intro was not merged in
- Supporting assets: 5 missing /images/cloud/*.png and 9 /snippets/
  files (cloud-banner, cloud/*, walletkit chain-abstraction/mobile
  linking snippets, chainlist, walletlist) the migrated content
  depends on

All internal /wallets, /apps, /WCT-token links within the migrated
content were rewritten to /network/wallets, /network/apps,
/network/WCT-token. One dead nav reference inherited from the source
repo (wallets/guides/app-extended-sessions, a file that doesn't exist
there either) was dropped rather than carried over broken.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: add Wallets/Apps/Network tabs and redirects for the migrated co…
5b55ed9 
…ntent

New tabs, mirroring the source site's structure with all page paths
prefixed /network/:
- Wallets (dropdowns: Wallet SDK Overview, Web, Android, iOS,
  Flutter, React Native, .NET) — chain support stays nested under
  Wallet SDK Overview > Chain Support, at /network/wallets/chains/*
- Apps (Getting Started, Installation, Guides)
- Network, restructured per request:
  - Getting started -> network/index (merged landing page)
  - new Participants group: Wallets, Apps, Custodians and
    Institutions, Service/Gateway Node Operators (service-nodes)
  - WCT Token: single consolidated group (overview, rewards,
    service-node-rewards, staking, faq, governance, contracts) —
    previously four separate groups (WCT Token/WCT Staking/
    Governance/WCT Smart Contracts) in the source nav

Redirects added for the old docs.walletconnect.network paths
(wallet-sdk/**, app-sdk/**, guides/**, custodians/**, walletguide/**,
token-dynamics/**, wct-staking/**, governance, contracts,
service-nodes, wallets, overview) to their new /network/* homes,
mirroring the source repo's own redirect table. This replaces a
pre-existing stale "/guides/** -> /custodians/**" redirect that
pointed at a path that never existed in this repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: fix homepage Wallets/Apps links to their /network/* home
49e340c 
Wallets and Apps content landed at /network/wallets and /network/apps
(not bare /wallets, /apps), so the homepage's product cards now point
to /network/wallets/overview and /network/apps/overview.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: restore global sidebar anchors and Report an Issue page
27b5aec 
The source site's navigation.global.anchors (WalletConnect, Blog,
Whitepaper, WalletConnect Specs, Report an Issue — rendered at the
bottom of the sidebar in the aspen theme) hadn't been carried over,
so the migrated tabs were missing part of the source's sidebar style.

Adds the anchors, pointing WalletConnect/Blog at the .com domain (matching
this repo's existing footer.socials.website convention) while leaving
Whitepaper/Specs on their own subdomains unchanged. Migrates
report-an-issue.mdx to the repo root (it's a site-wide utility page,
not network-specific) since the anchor now links to it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: apply file renames from the authoritative migration sheet
70a334e 
Cross-checked network/wallets against the WalletConnect docs pages
migration spreadsheet (source of truth for old->new URL mappings).
Structure stays under /network for now per direction, but applies the
renames the sheet calls out:

- network/wallets/best-practices.mdx -> network/wallets/more/best-practices.mdx
- network/wallets/more/staying-up-to-date.mdx -> .../more/updating-wallet-sdk.mdx
- network/wallets/more/from-web3wallet-*.mdx (7 files) -> nested under
  a new network/wallets/more/web3wallet-migration/ folder, renamed to
  quickstart/web/react-native/flutter/android/ios/unity.mdx
- network/wallets/walletguide/explorer-submission.mdx -> submit-wallet.mdx
- network/wallets/walletguide/explorer.mdx -> explorer-api.mdx
- network/wallets/walletguide/overview.mdx -> submit-chain.mdx
  (WalletGuide's nested "WalletGuide Chains"/"WalletGuide Wallets"
  subgroups flattened into one group, matching the sheet)

The old "Production" + "Upgrade" nav groups merge into a single "More"
group, matching the sheet's "new sidebar heading 'More', houses best
practices and upgrade from web3wallet info".

Updated docs.json nav paths, internal links in the renamed files, and
added specific redirects (ahead of the existing wildcard ones) so old
docs.walletconnect.network URLs for these renamed pages still resolve
correctly instead of 404ing under the generic /wallet-sdk/** and
/walletguide/** wildcard rules.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: promote wallets/ and apps/ out of /network to top-level
cf995b1 
Per the WalletConnect docs pages migration spreadsheet, the Wallet SDK
and App SDK content lives at bare /wallets and /apps, not nested under
/network (only Network/tokenomics content — overview, service-nodes,
WCT-token — stays under /network). network/wallets.mdx (the "Wallets"
network-participant page) is unaffected: it's a distinct page from the
wallets/ SDK folder, so no path collision.

- network/wallets/ -> wallets/
- network/apps/ -> apps/
- Rewrote every internal /network/wallets/* and /network/apps/* link
  repo-wide to /wallets/* and /apps/* (26 files, plus one pre-existing
  broken link in snippets/cloud/explorer-submission.mdx that pointed
  at the old pre-rename "explorer" filename)
- docs.json: stripped the network/ prefix from the Wallets/Apps tabs
  and from the Network tab's Participants references
  (wallets/custodians/*, apps/overview)
- Redirects: updated destinations from /network/wallets/* and
  /network/apps/* to the new bare paths

Also synced against the sheet's sidebar-structure reference table:
- Reordered WalletGuide nav (submit-wallet, wallet-list, submit-chain,
  chain-list, explorer-api) and WCT Token nav (FAQ moved to the end)
- Renamed "Custodians and Institutions" group to "Custodians & Institutions"
- Added sidebarTitle overrides where the sheet specifies a shorter
  sidebar label than the page title: wallets/overview -> "Quickstart",
  custodians/overview -> "Quickstart", custodians/extended-sessions ->
  "Extended Sessions Request", walletguide/submit-wallet -> "Submit New
  Wallet", walletguide/wallet-list -> "Wallet List",
  walletguide/submit-chain -> "Submit New Chain"

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: trim Network Participants group to match the sidebar sheet
867613d 
Removed Apps and the nested Custodians group from Participants,
leaving just Service Nodes and Wallets, matching the sheet's sidebar
reference table exactly. Custodians pages remain reachable via their
existing home in the Wallets tab's own dropdown.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@mintlify

mintlify Bot commented Sep 4, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Status Preview Updated
wc-pay-docs 🟢 Ready View Preview Sep 4, 2026, 10:18 AM

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

@juanisierra @claude
fix(scripts): stop generate-specs.mjs from wiping out non-API-Referen…
6ee8571 
…ce tabs

buildNavigation() rebuilt docs.json's entire navigation from scratch as
{versions: [...], global}, with each version's tabs array containing
only [Payments, API Reference]. If the update-specs CI workflow ran,
it would silently delete the Wallets, Apps, Network, and Webhook
Reference tabs (209+ nav pages) — the script predates this session and
was already dropping Webhook Reference, but the blast radius is much
bigger now.

The live docs.json actually uses tab-scoped versioning (the "API
Reference" tab itself has a versions array), not global versioning.
Fixed buildNavigation to regenerate just that one tab's versions and
splice it back into the existing tabs array, leaving every other tab
untouched. Removed the now-unused findPaymentsTab helper.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra
juanisierra requested a review from rtomas September 4, 2026 10:23
juanisierra and others added 2 commits September 4, 2026 13:09
@juanisierra @claude
docs: reorganize Payments sidebar into persona-first groups
11457d0 
Applies the nav restructuring from PR #84 (rtomas/improve-docs-sidebar),
scoped to only the Payments tab's groups — that PR's theme change,
homepage rework, and global-anchor removal are intentionally not
applied here since they're unrelated to the sidebar structure and
would undo other in-progress work.

- "WalletConnect Pay" -> "Get Started", nesting the four coverage
  pages under a new "Coverage & Reference" subgroup
- "WalletConnect Pay for Merchants" + "Merchant API" merged into one
  "For Merchants" group
- "WalletConnect Pay for PSPs" -> "For PSPs", moved earlier (now
  second, after Get Started)
- "WalletConnect Pay for Wallets" -> "For Wallets": "Integrate using
  the Wallet SDK" -> "Integrate Wallet SDK"; tap-to-pay moved up to
  sit right after api-first
- "Ecommerce and Online Checkout" -> "For Checkout"
- "WalletConnect AI Agent SDK" -> "AI Agents"

PR #84's branch predates test-mode, webhooks, and wallets/webview
being added to this tab, so those three pages aren't in its diff —
folded them into their logical new homes (test-mode/webhooks into Get
Started, webview into For Wallets) rather than dropping them.

No file paths changed — this is a pure nav relabel/regroup, so no
links needed fixing. Verified all 209 nav pages across every tab still
resolve to real files.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
fix(home): remove empty grey pill from ProductCard when model is unset
6aafeb0 
Neither the root homepage nor the payments homepage ever pass a
"model" prop to ProductCard, so the grey pill span always rendered
empty next to the blue type badge (Wallet SDK, App SDK, Payments,
Network). Now it only renders when model is actually provided.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: move API Reference tab to a global link, Specs into Network sid…
3460a0f 
…ebar

Researched Mintlify's published JSON schema (mintlify.com/docs.json)
to confirm the right approach: a tab's "groups" and "anchors" are
mutually exclusive (every anyOf variant has additionalProperties:
false), and a group's "pages" array only accepts page-path strings or
nested group objects — no raw external-link items. So neither "add
anchors alongside groups on one tab" nor "put a link in Network's
pages array" are valid shapes.

- Removed the "API Reference" tab entirely; replaced the
  "WalletConnect Specs" global anchor with "API Reference" in the same
  position, keeping its "code" icon, pointing at
  /payments/api-reference. This is now visible on every tab, as
  requested. The underlying payments/api-reference/* pages and
  redirects are untouched — only the sidebar tab entry point is gone.
- Added network/specs.mdx (a real internal page with a Card linking
  out to specs.walletconnect.com) as a new "Resources" group at the
  bottom of the Network tab, approximating "Specs at the bottom of the
  Network sidebar" within schema constraints.

Verified: every tab now uses exactly one content shape (no
groups+anchors mixing), and all 161 nav pages still resolve to real
files.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: fold Webhook Reference tab into Payments' webhooks section
8e69b5c 
payments/webhooks.mdx (the webhooks guide) only links out to
/payments/webhook-event-reference for field-level details rather than
including that content, so the standalone "Webhook Reference" tab
wasn't redundant — it needed folding in, not just deleting.

Removed the tab and nested its 8 pages (webhook-event-reference plus
the 7 payment-<stage> event detail pages) as a "Webhook Reference"
group inside the Payments tab's "Get Started" group, right after
payments/webhooks. No file paths changed, so the existing cross-links
between webhooks.mdx and these pages still work as-is.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: restore full API Reference tab as "Payments API Reference"
e82775c 
Reverts the earlier "fold API Reference into a single global anchor
link" change: that dropped all sidebar browsability for the 51
versioned endpoint pages (Overview/Gateway/Payments/Refunds/Merchants
groups, Latest/Preview version switcher) since a nested group can't
carry Mintlify's "versions" property — confirmed via the published
schema.

Restored the full tab (unchanged structure) renamed to "Payments API
Reference", reinserted right after the Payments tab. The global anchor
that used to point at the tab now points at the same
/payments/api-reference URL under the new label "Payments API
Reference" — since that page belongs to the tab, landing on it via the
anchor now correctly shows the full sidebar tree again, from any tab.

Updated generate-specs.mjs's tab-name match ("API Reference" ->
"Payments API Reference") so future spec regeneration still finds and
replaces the right tab instead of silently no-op'ing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: rename "Payments API Reference" tab to "Payments API reference"
8837e1c 
Sentence case, matching the site's existing convention (e.g. "Webhook
event reference"). Updated the tab name, the matching global anchor
label, and generate-specs.mjs's tab-name match so future regeneration
still finds the right tab.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: rename API Reference tab back to "API Reference"
a0aac19 
Updated the tab name, the matching global anchor label, and
generate-specs.mjs's tab-name match to stay in sync.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: remove the API Reference global sidebar anchor
dbba2fd 
Now that the API Reference tab itself is restored and visible in the
top tab bar, the anchor shortcut is redundant. Global anchors are back
to: WalletConnect, Blog, Whitepaper, Report an Issue.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: add a Home tab containing only the main page
02c2068 
New first tab, "Home", with pages: ["index"] and nothing else - no
groups, no other pages to browse. index.mdx already uses mode: "frame"
in its frontmatter, which renders without the standard sidebar chrome,
so this tab shows just the homepage with no sidebar navigation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
@juanisierra @claude
docs: remove the Home tab
31a8664 
index.mdx stays at the repo root and continues to render at / — it
doesn't need to be listed in any tab's nav to be reachable there,
same as before the Home tab was added.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzTGS8bJLU4QvnDsthWChe
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rtomas rtomas Awaiting requested review from rtomas

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@juanisierra