PR: x402-react-client

[Johnnnex]

Description

This PR adds x402-react-client, a React SDK that dramatically simplifies x402 payment integration for React and Next.js applications.

What's included:

Core Package (packages/x402-react-client/)

• X402Provider - Configures wallet connections, blockchain providers, and RainbowKit UI with zero config
• useX402Payment() - Handles the entire payment flow: 402 detection, chain switching, payment signing, and automatic retries
• useX402Balance() - Real-time ERC20 token balance tracking with block watching and polling
• Comprehensive TypeScript types and JSDoc documentation
• Re-exports of common wagmi/RainbowKit utilities to prevent context fragmentation

Demo Application (examples/fullstack/nextjs-enhanced/)

• Live examples showcasing all SDK features
• Demonstrates JSON, streaming, and blob response types
• Payment receipt handling and transaction logging
• Production-ready Next.js implementation

Why this is needed:

Currently, developers integrating x402 into React apps must manually:

• Configure wagmi, RainbowKit, and TanStack Query
• Parse 402 responses and extract payment requirements
• Handle chain switching logic
• Implement payment signing flows
• Retry requests with payment proofs
• Parse payment receipts from response headers

This SDK abstracts all of that into two hooks and one provider component. Integration time goes from hours to minutes :).

Developer Experience:

// Before: 100+ lines of boilerplate
// After:
import { X402Provider, useX402Payment } from 'x402-react-client';

<X402Provider config={{ appName: "My App" }}>
  <App />
</X402Provider>

const { pay, data, receipt } = useX402Payment();
await pay('/api/protected-endpoint');

No related issue - this is a new feature addition to improve the React/Next.js developer experience.

Tests

Manual Testing Performed:

Extensively tested the demo app (nextjs-enhanced) with the following scenarios:

Payment Flows:

• Basic JSON responses with useX402Payment()
• POST requests with JSON bodies
• Streaming responses (SSE-style data)
• File downloads (blob responses)
• Payment receipt extraction from X-PAYMENT-RESPONSE headers
• Error handling (user rejection, network failures, invalid endpoints)

Wallet Integration:

• Wallet connection and signing
• Chain switching (Base, Polygon, Avalanche and their respective testnets)
• Account disconnection and reconnection
• Balance tracking across chain switches

Balance Hook (useX402Balance):

• Real-time balance updates via block watching
• Fallback polling when block watching fails
• Manual refresh triggering
• Callback behavior with callbackOnPoll option
• Custom token address support

Edge Cases:

• SSR/hydration (Next.js App Router compatibility)
• Wallet not connected state (error)
• Unsupported network errors
• Context isolation (re-exported utilities work correctly)

Automated Tests:

Note: Integration tests for the React hooks would require a full wagmi/viem test environment. The manual testing via the demo app provides comprehensive coverage of all user-facing functionality.

Checklist

• [x] I have formatted and linted my code (pnpm format && pnpm lint from /typescript)
• [x] All new and existing tests pass (pnpm test from /typescript)
• [x] My commits are signed

---

Additional Notes

About the 35+ file changes:

This includes:

• 3 core React components/hooks with full documentation
• Complete TypeScript type definitions
• Comprehensive README with usage examples
• Full demo application (nextjs-enhanced) with multiple examples
• Package configuration files (package.json, tsconfig.json, etc.)
• Re-exports to maintain context consistency (in entry point, index)

Package Design Decisions:

1. Re-exports over direct imports: Prevents context fragmentation issues when users mix imports from different packages
2. Response type flexibility: Supports JSON, text, blob, stream, and raw Response objects for maximum flexibility
3. Callback design: useX402Balance callbacks only fire on manual refresh by default to prevent unnecessary re-renders
4. SSR safety: Provider only renders client-side to prevent Next.js hydration mismatches

Future Improvements (out of scope for this PR):

• Unit tests for hooks using wagmi test utilities
• More demo examples (complex flows, multi-step payments)
• Additional chain support beyond the default six

Happy to address any feedback or questions!

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel[bot]]

@Johnnnex is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.