@walletconnect/pay-appkit

The official Reown AppKit adapter for the headless WalletConnect Pay SDK.

It implements the WalletProvider seam that @walletconnect/pay-state expects, on top of a live AppKit instance — so a host that already uses AppKit for wallet connection can drive the headless WC Pay runtime without writing its own wallet glue.

What's inside

• createAppKitWalletProvider (main entry) — builds the framework-neutral WalletProvider seam (getAccounts, getProvider, switchNetwork, subscribe, …) over an AppKit instance. No React.
• loadSolanaWeb3 (main entry) — the lazy @solana/web3.js codec loader the Solana signing strategy needs, with a shared dynamic-import cache.
• useAppKitWalletProvider (/react entry) — a React hook that returns a connect-capable WalletProvider (ready to hand to usePaymentSession) plus everything a host needs to build its own connect UI: the wallet picker list (wallets / allWallets / fetchWallets), the WalletConnect URI (wcUri / getWcUri), and the per-namespace connected-wallet list.

Two entry points — React stays off the main one

@walletconnect/pay-appkit          → createAppKitWalletProvider, loadSolanaWeb3   (framework-neutral)
@walletconnect/pay-appkit/react    → useAppKitWalletProvider                       (React; AppKit is headless here)

The split is deliberate: the main entry never imports React, so a non-React host (or the server) can use the seam without pulling React in as a peer dep. The connect flow (which needs AppKit's React hooks) lives only on /react.

Headless usage (host owns the connect UI)

import { useAppKitWalletProvider } from '@walletconnect/pay-appkit/react'
import { usePaymentSession } from '@walletconnect/pay-react'

function Checkout({ paymentId, seams }) {
  // `wallet` is the WalletProvider seam; `wallets` / `wcUri` drive your own connect UI.
  const { wallet, wallets, wcUri, connect } = useAppKitWalletProvider()

  const session = usePaymentSession({ paymentId, seams, wallet })
  // render your own wallet picker from `wallets`, show `wcUri` as a QR, etc.
}

createAppKitWalletProvider (no React) is the building block; useAppKitWalletProvider wires it to a live AppKit instance and adds the connect affordances.

Boundaries

• Depends on @walletconnect/pay-core + @walletconnect/pay-state (workspace). It does not depend on the BX app — it is a reusable adapter.
• Peer deps: @reown/appkit (^1.8), @solana/web3.js (^1.98), react (>=18, only for the /react entry).
• AppKit runs headless here — there is no modal. Connection is programmatic (the host renders the picker and calls connect).

License note

@reown/appkit is under the Reown Community License (not OSS). WalletConnect and Reown are the same entity, so this internal/private package is fine — but confirm legal clearance before any external/public publish of pay-appkit.