From 8191dd6399955108dc715f13e883bcffb1c37b55 Mon Sep 17 00:00:00 2001 From: Enes Date: Thu, 23 Jul 2026 01:08:40 +0300 Subject: [PATCH 1/3] docs(headless-sdk): add "Build with AI" skill page Adds a page under the Headless SDK section that promotes the walletconnect-pay-headless Agent Skill (from WalletConnect/skills), so developers can install it with `npx skills add` and have their AI assistant scaffold a correct headless checkout. Covers install (npm/pnpm/bun), example prompts, what's included, and supported agents. Added to both docs.json nav entries. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 6 +- payments/psps/headless-sdk/build-with-ai.mdx | 85 ++++++++++++++++++++ 2 files changed, 89 insertions(+), 2 deletions(-) create mode 100644 payments/psps/headless-sdk/build-with-ai.mdx diff --git a/docs.json b/docs.json index ba7c10a..31e0c53 100644 --- a/docs.json +++ b/docs.json @@ -108,7 +108,8 @@ "payments/psps/headless-sdk/overview", "payments/psps/headless-sdk/how-it-works", "payments/psps/headless-sdk/implementation", - "payments/psps/headless-sdk/packages-reference" + "payments/psps/headless-sdk/packages-reference", + "payments/psps/headless-sdk/build-with-ai" ] } ] @@ -268,7 +269,8 @@ "payments/psps/headless-sdk/overview", "payments/psps/headless-sdk/how-it-works", "payments/psps/headless-sdk/implementation", - "payments/psps/headless-sdk/packages-reference" + "payments/psps/headless-sdk/packages-reference", + "payments/psps/headless-sdk/build-with-ai" ] } ] diff --git a/payments/psps/headless-sdk/build-with-ai.mdx b/payments/psps/headless-sdk/build-with-ai.mdx new file mode 100644 index 0000000..9264ba6 --- /dev/null +++ b/payments/psps/headless-sdk/build-with-ai.mdx @@ -0,0 +1,85 @@ +--- +title: "Build with AI" +sidebarTitle: "Build with AI" + +metatags: + description: "Give your AI coding assistant deep, accurate knowledge of the WalletConnect Pay Headless SDK. Install the walletconnect-pay-headless skill with one command and let Claude Code, Cursor, Codex, and other agents scaffold your branded checkout correctly." +--- + +Give your AI coding assistant deep, accurate knowledge of the WalletConnect Pay Headless SDK. The **`walletconnect-pay-headless`** [Agent Skill](https://skills.sh) teaches your agent the runtime model, the five seams, the 17-state payment snapshot, and the exact code for the server proxy, wallet connection, and render loop — so it scaffolds a correct integration instead of guessing. + + + A Skill is a portable package of procedural knowledge an AI agent loads on demand. This one is maintained alongside the SDK in [`WalletConnect/skills`](https://github.com/WalletConnect/skills), so it stays in lockstep with the `@walletconnect/pay-*` packages. + + +## Install + +Install the skill into your project with a single command: + + + +```bash npm +npx skills add WalletConnect/skills/walletconnect-pay-headless +``` + +```bash pnpm +pnpm dlx skills add WalletConnect/skills/walletconnect-pay-headless +``` + +```bash bun +bunx skills add WalletConnect/skills/walletconnect-pay-headless +``` + + + +Once installed, your assistant automatically loads the skill when you ask it to work on a WalletConnect Pay headless checkout. Learn more about the ecosystem at [skills.sh](https://skills.sh). + +## Try it + +With the skill installed, ask your assistant things like: + +- _"Add a WalletConnect Pay headless checkout to my Next.js app."_ +- _"Wire the server proxy so my Engine API key stays server-side."_ +- _"Render the payment options and confirm step from the snapshot."_ +- _"How do I handle the Permit2 approve-and-pay step?"_ +- _"Build a framework-neutral checkout with `createPaymentController`."_ + +## What's included + + + + The headless runtime + host model, the five injectable seams (`Transport`, `WalletProvider`, `Signer`, `Clock`, `Telemetry`), and which ones you wire vs. which the SDK ships. + + + All 17 `PaymentState` values mapped to what to render and which action to call, plus the exact `PaymentSnapshot` fields — the whole UI contract in one table. + + + The five Engine routes and the server-side `createEngineClient`, with the guarantee that the API key never reaches the browser. + + + `usePaymentSession` + ``, the memoized seam assembly, and the full render switch. + + + `createPaymentController` with manual `subscribe` and imperative render — framework-neutral. + + + Bring your own `WalletProvider` seam and compose the raw `EvmSigningStrategy` / `SolanaSigningStrategy` when you are not using AppKit. + + + +Every snippet in the skill is grounded in the [reference checkout](https://github.com/WalletConnect/walletconnect-pay-examples/tree/main/gateway/headless-checkout) and the published SDK types — the same sources as these docs. + +## Supported agents + +The skill follows the open [Agent Skills](https://skills.sh) specification and works with any compatible assistant, including **Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini, Cline**, and more. + +## Next steps + + + + The payment lifecycle, the host + seams model, and how the API key stays server-side. + + + Build a complete checkout in React / Next.js, step by step. + + From 925aec80836d4256f21bffd976aa5e4463d29c77 Mon Sep 17 00:00:00 2001 From: Enes Date: Thu, 23 Jul 2026 01:19:59 +0300 Subject: [PATCH 2/3] docs(headless-sdk): rename page to Skills (title + slug) Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 4 ++-- payments/psps/headless-sdk/{build-with-ai.mdx => skills.mdx} | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) rename payments/psps/headless-sdk/{build-with-ai.mdx => skills.mdx} (98%) diff --git a/docs.json b/docs.json index 31e0c53..0904006 100644 --- a/docs.json +++ b/docs.json @@ -109,7 +109,7 @@ "payments/psps/headless-sdk/how-it-works", "payments/psps/headless-sdk/implementation", "payments/psps/headless-sdk/packages-reference", - "payments/psps/headless-sdk/build-with-ai" + "payments/psps/headless-sdk/skills" ] } ] @@ -270,7 +270,7 @@ "payments/psps/headless-sdk/how-it-works", "payments/psps/headless-sdk/implementation", "payments/psps/headless-sdk/packages-reference", - "payments/psps/headless-sdk/build-with-ai" + "payments/psps/headless-sdk/skills" ] } ] diff --git a/payments/psps/headless-sdk/build-with-ai.mdx b/payments/psps/headless-sdk/skills.mdx similarity index 98% rename from payments/psps/headless-sdk/build-with-ai.mdx rename to payments/psps/headless-sdk/skills.mdx index 9264ba6..9970307 100644 --- a/payments/psps/headless-sdk/build-with-ai.mdx +++ b/payments/psps/headless-sdk/skills.mdx @@ -1,6 +1,6 @@ --- -title: "Build with AI" -sidebarTitle: "Build with AI" +title: "Skills" +sidebarTitle: "Skills" metatags: description: "Give your AI coding assistant deep, accurate knowledge of the WalletConnect Pay Headless SDK. Install the walletconnect-pay-headless skill with one command and let Claude Code, Cursor, Codex, and other agents scaffold your branded checkout correctly." From 82923a0dccc697bb28b811e3811f05db8a99e29e Mon Sep 17 00:00:00 2001 From: Enes Date: Thu, 23 Jul 2026 13:14:23 +0300 Subject: [PATCH 3/3] docs(headless-sdk): promote the skill via a banner, drop the standalone page Single source of truth: rather than a separate Skills page that risks drifting from the SDK docs, add a discovery banner to the Headless SDK overview and implementation pages pointing to the skill + install command. Removes skills.mdx and its nav entry. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 6 +- payments/psps/headless-sdk/implementation.mdx | 8 ++ payments/psps/headless-sdk/overview.mdx | 8 ++ payments/psps/headless-sdk/skills.mdx | 85 ------------------- 4 files changed, 18 insertions(+), 89 deletions(-) delete mode 100644 payments/psps/headless-sdk/skills.mdx diff --git a/docs.json b/docs.json index 0904006..ba7c10a 100644 --- a/docs.json +++ b/docs.json @@ -108,8 +108,7 @@ "payments/psps/headless-sdk/overview", "payments/psps/headless-sdk/how-it-works", "payments/psps/headless-sdk/implementation", - "payments/psps/headless-sdk/packages-reference", - "payments/psps/headless-sdk/skills" + "payments/psps/headless-sdk/packages-reference" ] } ] @@ -269,8 +268,7 @@ "payments/psps/headless-sdk/overview", "payments/psps/headless-sdk/how-it-works", "payments/psps/headless-sdk/implementation", - "payments/psps/headless-sdk/packages-reference", - "payments/psps/headless-sdk/skills" + "payments/psps/headless-sdk/packages-reference" ] } ] diff --git a/payments/psps/headless-sdk/implementation.mdx b/payments/psps/headless-sdk/implementation.mdx index a25597a..f62162b 100644 --- a/payments/psps/headless-sdk/implementation.mdx +++ b/payments/psps/headless-sdk/implementation.mdx @@ -6,6 +6,14 @@ metatags: description: "Build a branded WalletConnect Pay checkout with the @walletconnect/pay-* Headless SDK. A step-by-step walkthrough — server proxy, transport, zero-config AppKit, and rendering the snapshot — with React and JavaScript examples side by side." --- + + **Prefer to let an AI agent build this?** Install the WalletConnect Pay Headless [skill](https://github.com/WalletConnect/skills/tree/main/skills/walletconnect-pay-headless) — with it loaded, Claude Code, Cursor, Codex, and other agents can scaffold the steps below directly in your codebase: + + ```bash + npx skills add WalletConnect/skills/walletconnect-pay-headless + ``` + + This page walks through building a complete checkout on the Headless SDK, with **React / Next.js** and **JavaScript** examples side by side. New to the SDK? Read [How it works](/payments/psps/headless-sdk/how-it-works) first for the architecture and the role of each seam. Wallet connection is now **zero-config**: the SDK owns the entire Reown AppKit setup. You install only the `@walletconnect/pay-*` packages and never touch `@reown/*`, `wagmi`, or `viem` directly. diff --git a/payments/psps/headless-sdk/overview.mdx b/payments/psps/headless-sdk/overview.mdx index b26f47b..1387112 100644 --- a/payments/psps/headless-sdk/overview.mdx +++ b/payments/psps/headless-sdk/overview.mdx @@ -6,6 +6,14 @@ metatags: description: "Build your own branded crypto checkout on WalletConnect Pay with the Headless SDK — a set of framework-agnostic @walletconnect/pay-* packages that own the payment flow while you own the UI, transport, and wallet connection." --- + + **Building with an AI coding agent?** Install the WalletConnect Pay Headless [skill](https://github.com/WalletConnect/skills/tree/main/skills/walletconnect-pay-headless) and your agent (Claude Code, Cursor, Codex, and others) can scaffold this integration for you: + + ```bash + npx skills add WalletConnect/skills/walletconnect-pay-headless + ``` + + The Headless SDK is a set of framework-agnostic [`@walletconnect/pay-*`](https://www.npmjs.com/org/walletconnect) packages that own the WalletConnect Pay payment flow while you own the UI. It's the exact runtime that powers our own hosted Buyer Experience — extracted so you can build a fully branded, fully owned checkout on the same engine. You get the payment state machine, Engine API client, and wallet orchestration; you bring your own UI, branding, routing, and infrastructure. diff --git a/payments/psps/headless-sdk/skills.mdx b/payments/psps/headless-sdk/skills.mdx deleted file mode 100644 index 9970307..0000000 --- a/payments/psps/headless-sdk/skills.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Skills" -sidebarTitle: "Skills" - -metatags: - description: "Give your AI coding assistant deep, accurate knowledge of the WalletConnect Pay Headless SDK. Install the walletconnect-pay-headless skill with one command and let Claude Code, Cursor, Codex, and other agents scaffold your branded checkout correctly." ---- - -Give your AI coding assistant deep, accurate knowledge of the WalletConnect Pay Headless SDK. The **`walletconnect-pay-headless`** [Agent Skill](https://skills.sh) teaches your agent the runtime model, the five seams, the 17-state payment snapshot, and the exact code for the server proxy, wallet connection, and render loop — so it scaffolds a correct integration instead of guessing. - - - A Skill is a portable package of procedural knowledge an AI agent loads on demand. This one is maintained alongside the SDK in [`WalletConnect/skills`](https://github.com/WalletConnect/skills), so it stays in lockstep with the `@walletconnect/pay-*` packages. - - -## Install - -Install the skill into your project with a single command: - - - -```bash npm -npx skills add WalletConnect/skills/walletconnect-pay-headless -``` - -```bash pnpm -pnpm dlx skills add WalletConnect/skills/walletconnect-pay-headless -``` - -```bash bun -bunx skills add WalletConnect/skills/walletconnect-pay-headless -``` - - - -Once installed, your assistant automatically loads the skill when you ask it to work on a WalletConnect Pay headless checkout. Learn more about the ecosystem at [skills.sh](https://skills.sh). - -## Try it - -With the skill installed, ask your assistant things like: - -- _"Add a WalletConnect Pay headless checkout to my Next.js app."_ -- _"Wire the server proxy so my Engine API key stays server-side."_ -- _"Render the payment options and confirm step from the snapshot."_ -- _"How do I handle the Permit2 approve-and-pay step?"_ -- _"Build a framework-neutral checkout with `createPaymentController`."_ - -## What's included - - - - The headless runtime + host model, the five injectable seams (`Transport`, `WalletProvider`, `Signer`, `Clock`, `Telemetry`), and which ones you wire vs. which the SDK ships. - - - All 17 `PaymentState` values mapped to what to render and which action to call, plus the exact `PaymentSnapshot` fields — the whole UI contract in one table. - - - The five Engine routes and the server-side `createEngineClient`, with the guarantee that the API key never reaches the browser. - - - `usePaymentSession` + ``, the memoized seam assembly, and the full render switch. - - - `createPaymentController` with manual `subscribe` and imperative render — framework-neutral. - - - Bring your own `WalletProvider` seam and compose the raw `EvmSigningStrategy` / `SolanaSigningStrategy` when you are not using AppKit. - - - -Every snippet in the skill is grounded in the [reference checkout](https://github.com/WalletConnect/walletconnect-pay-examples/tree/main/gateway/headless-checkout) and the published SDK types — the same sources as these docs. - -## Supported agents - -The skill follows the open [Agent Skills](https://skills.sh) specification and works with any compatible assistant, including **Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini, Cline**, and more. - -## Next steps - - - - The payment lifecycle, the host + seams model, and how the API key stays server-side. - - - Build a complete checkout in React / Next.js, step by step. - -