@payai/x402-solana-react 2.0.0-canary.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +71 -62
  2. package/dist/hooks/useX402Payment.d.ts +2 -1
  3. package/dist/hooks/useX402Payment.d.ts.map +1 -1
  4. package/dist/index.js +2 -2
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +152 -135
  7. package/dist/index.mjs.map +1 -1
  8. package/package.json +5 -5
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # x402 Solana React Paywall
2
2
 
3
- A reusable React component library that provides drop-in paywall functionality for Solana-based applications using the x402 payment protocol.
3
+ A reusable React component library that provides drop-in paywall functionality for Solana-based applications using the x402 payment protocol v2.
4
+
5
+ > **x402 Protocol v2**: This package uses `x402-solana` which implements the x402 v2 specification with CAIP-2 network identifiers, `PAYMENT-SIGNATURE` headers, and improved payload structure. See the [CHANGELOG](./CHANGELOG.md) for details.
4
6
 
5
7
  ## Classic theme
6
8
 
@@ -119,8 +121,8 @@ npm install @solana/wallet-adapter-react @solana/wallet-adapter-react-ui @solana
119
121
  Import the required styles in your main file (e.g., `main.tsx` or `App.tsx`):
120
122
 
121
123
  ```tsx
122
- import "@payai/x402-solana-react/styles";
123
- import "@solana/wallet-adapter-react-ui/styles.css";
124
+ import '@payai/x402-solana-react/styles';
125
+ import '@solana/wallet-adapter-react-ui/styles.css';
124
126
  ```
125
127
 
126
128
  ### 2. Environment Variables (Optional - Recommended for Production)
@@ -143,7 +145,7 @@ Restart the dev server after changing `.env` so Vite picks up updates.
143
145
  The component automatically sets up wallet providers for you! Just use it directly:
144
146
 
145
147
  ```tsx
146
- import { X402Paywall } from "@payai/x402-solana-react";
148
+ import { X402Paywall } from '@payai/x402-solana-react';
147
149
 
148
150
  function App() {
149
151
  return (
@@ -163,17 +165,11 @@ function App() {
163
165
  Wrap your app with Solana wallet providers:
164
166
 
165
167
  ```tsx
166
- import { WalletAdapterNetwork } from "@solana/wallet-adapter-base";
167
- import {
168
- ConnectionProvider,
169
- WalletProvider,
170
- } from "@solana/wallet-adapter-react";
171
- import { WalletModalProvider } from "@solana/wallet-adapter-react-ui";
172
- import {
173
- PhantomWalletAdapter,
174
- SolflareWalletAdapter,
175
- } from "@solana/wallet-adapter-wallets";
176
- import { clusterApiUrl } from "@solana/web3.js";
168
+ import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
169
+ import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react';
170
+ import { WalletModalProvider } from '@solana/wallet-adapter-react-ui';
171
+ import { PhantomWalletAdapter, SolflareWalletAdapter } from '@solana/wallet-adapter-wallets';
172
+ import { clusterApiUrl } from '@solana/web3.js';
177
173
 
178
174
  function App() {
179
175
  const network = WalletAdapterNetwork.Mainnet;
@@ -204,9 +200,9 @@ function App() {
204
200
  ### Simplest Example (Auto-Setup)
205
201
 
206
202
  ```tsx
207
- import { X402Paywall } from "@payai/x402-solana-react";
208
- import "@payai/x402-solana-react/styles";
209
- import "@solana/wallet-adapter-react-ui/styles.css";
203
+ import { X402Paywall } from '@payai/x402-solana-react';
204
+ import '@payai/x402-solana-react/styles';
205
+ import '@solana/wallet-adapter-react-ui/styles.css';
210
206
 
211
207
  function PremiumPage() {
212
208
  return (
@@ -214,7 +210,7 @@ function PremiumPage() {
214
210
  amount={0.02}
215
211
  description="Premium AI Chat Access"
216
212
  network="solana" // Use 'solana' for mainnet, 'solana-devnet' for testing
217
- onPaymentSuccess={(txId) => console.log("Payment successful!", txId)}
213
+ onPaymentSuccess={txId => console.log('Payment successful!', txId)}
218
214
  >
219
215
  <PremiumContent />
220
216
  </X402Paywall>
@@ -225,7 +221,7 @@ function PremiumPage() {
225
221
  ### With Custom RPC (Recommended for Production)
226
222
 
227
223
  ```tsx
228
- import { X402Paywall } from "@payai/x402-solana-react";
224
+ import { X402Paywall } from '@payai/x402-solana-react';
229
225
 
230
226
  function PremiumPage() {
231
227
  // Set via environment variable: VITE_SOLANA_RPC_URL
@@ -237,12 +233,12 @@ function PremiumPage() {
237
233
  description="Premium Content"
238
234
  network="solana"
239
235
  rpcUrl={rpcUrl} // Avoids rate limiting on public RPCs
240
- onPaymentSuccess={(txId) => {
241
- console.log("Payment successful!", txId);
236
+ onPaymentSuccess={txId => {
237
+ console.log('Payment successful!', txId);
242
238
  // Update your backend, show success message, etc.
243
239
  }}
244
- onPaymentError={(error) => {
245
- console.error("Payment failed:", error);
240
+ onPaymentError={error => {
241
+ console.error('Payment failed:', error);
246
242
  }}
247
243
  >
248
244
  <PremiumContent />
@@ -268,11 +264,11 @@ The component comes with multiple built-in themes:
268
264
  ### Theme Example
269
265
 
270
266
  ```tsx
271
- import { X402Paywall } from "@payai/x402-solana-react";
272
- import { useState } from "react";
267
+ import { X402Paywall } from '@payai/x402-solana-react';
268
+ import { useState } from 'react';
273
269
 
274
270
  function PremiumPage() {
275
- const [theme, setTheme] = useState("light");
271
+ const [theme, setTheme] = useState('light');
276
272
 
277
273
  return (
278
274
  <X402Paywall
@@ -280,7 +276,7 @@ function PremiumPage() {
280
276
  description="Premium Features"
281
277
  network="solana"
282
278
  theme={theme} // Try: 'light', 'dark', 'solana-light', 'solana-dark', etc.
283
- onPaymentSuccess={(txId) => console.log("Paid!", txId)}
279
+ onPaymentSuccess={txId => console.log('Paid!', txId)}
284
280
  >
285
281
  <AdvancedFeatures />
286
282
  </X402Paywall>
@@ -299,11 +295,11 @@ You can customize further using `classNames` and `customStyles` props:
299
295
  network="solana"
300
296
  theme="dark"
301
297
  classNames={{
302
- container: "bg-gradient-to-r from-purple-600 to-blue-600",
303
- button: "bg-white text-purple-600 hover:bg-gray-50 font-bold",
298
+ container: 'bg-gradient-to-r from-purple-600 to-blue-600',
299
+ button: 'bg-white text-purple-600 hover:bg-gray-50 font-bold',
304
300
  }}
305
301
  customStyles={{
306
- button: { boxShadow: "0 10px 30px rgba(153, 69, 255, 0.4)" },
302
+ button: { boxShadow: '0 10px 30px rgba(153, 69, 255, 0.4)' },
307
303
  }}
308
304
  >
309
305
  <AdvancedFeatures />
@@ -314,32 +310,32 @@ You can customize further using `classNames` and `customStyles` props:
314
310
 
315
311
  ### X402Paywall Props
316
312
 
317
- | Prop | Type | Required | Default | Description |
318
- | -------------------- | ----------------------------- | -------- | ----------------- | ----------------------------------------------------------- |
319
- | `amount` | `number` | ✅ | - | Payment amount in USDC |
320
- | `description` | `string` | ✅ | - | Payment description |
321
- | `children` | `ReactNode` | ✅ | - | Protected content to show after payment |
322
- | `network` | `'solana' \| 'solana-devnet'` | ❌ | `'solana-devnet'` | Solana network to use |
323
- | `wallet` | `WalletAdapter` | ❌ | - | Optional wallet adapter (auto-uses context if not provided) |
324
- | `rpcUrl` | `string` | ❌ | - | Custom RPC URL (recommended to avoid rate limits) |
325
- | `autoSetupProviders` | `boolean` | ❌ | `true` | Automatically setup wallet providers |
326
- | `providerNetwork` | `WalletAdapterNetwork` | ❌ | Auto-detected | Network for auto-setup providers |
327
- | `providerEndpoint` | `string` | ❌ | - | Custom endpoint for auto-setup providers |
328
- | `apiEndpoint` | `string` | ❌ | `https://x402.payai.network/api/solana/paid-content` | Custom API endpoint |
329
- | `facilitatorUrl` | `string` | ❌ | - | Custom facilitator URL |
330
- | `theme` | `ThemePreset` | ❌ | `'solana-light'` | Visual theme (see Themes section) |
331
- | `logoUrl` | `string` | ❌ | - | Custom logo URL to display |
332
- | `showBalance` | `boolean` | ❌ | `true` | Show wallet USDC balance |
333
- | `showNetworkInfo` | `boolean` | ❌ | `true` | Show network information |
334
- | `showPaymentDetails` | `boolean` | ❌ | `true` | Show payment details section |
335
- | `maxPaymentAmount` | `number` | ❌ | - | Maximum allowed payment amount |
336
- | `classNames` | `ComponentClassNames` | ❌ | - | Custom CSS classes for components |
337
- | `customStyles` | `ComponentStyles` | ❌ | - | Custom inline styles for components |
338
- | `onPaymentStart` | `() => void` | ❌ | - | Callback when payment starts |
339
- | `onPaymentSuccess` | `(txId: string) => void` | ❌ | - | Callback on successful payment |
340
- | `onPaymentError` | `(error: Error) => void` | ❌ | - | Callback on payment error |
341
- | `onWalletConnect` | `(publicKey: string) => void` | ❌ | - | Callback when wallet connects |
342
- | `onDisconnect` | `() => void` | ❌ | - | Callback when wallet disconnects |
313
+ | Prop | Type | Required | Default | Description |
314
+ | -------------------- | ----------------------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------- |
315
+ | `amount` | `number` | ✅ | - | Payment amount in USDC |
316
+ | `description` | `string` | ✅ | - | Payment description |
317
+ | `children` | `ReactNode` | ✅ | - | Protected content to show after payment |
318
+ | `network` | `'solana' \| 'solana-devnet'` | ❌ | `'solana-devnet'` | Solana network to use |
319
+ | `wallet` | `WalletAdapter` | ❌ | - | Optional wallet adapter (auto-uses context if not provided) |
320
+ | `rpcUrl` | `string` | ❌ | - | Custom RPC URL (recommended to avoid rate limits) |
321
+ | `autoSetupProviders` | `boolean` | ❌ | `true` | Automatically setup wallet providers |
322
+ | `providerNetwork` | `WalletAdapterNetwork` | ❌ | Auto-detected | Network for auto-setup providers |
323
+ | `providerEndpoint` | `string` | ❌ | - | Custom endpoint for auto-setup providers |
324
+ | `apiEndpoint` | `string` | ❌ | `https://x402.payai.network/api/solana/paid-content` | Custom API endpoint |
325
+ | `facilitatorUrl` | `string` | ❌ | - | Custom facilitator URL |
326
+ | `theme` | `ThemePreset` | ❌ | `'solana-light'` | Visual theme (see Themes section) |
327
+ | `logoUrl` | `string` | ❌ | - | Custom logo URL to display |
328
+ | `showBalance` | `boolean` | ❌ | `true` | Show wallet USDC balance |
329
+ | `showNetworkInfo` | `boolean` | ❌ | `true` | Show network information |
330
+ | `showPaymentDetails` | `boolean` | ❌ | `true` | Show payment details section |
331
+ | `maxPaymentAmount` | `number` | ❌ | - | Maximum allowed payment amount |
332
+ | `classNames` | `ComponentClassNames` | ❌ | - | Custom CSS classes for components |
333
+ | `customStyles` | `ComponentStyles` | ❌ | - | Custom inline styles for components |
334
+ | `onPaymentStart` | `() => void` | ❌ | - | Callback when payment starts |
335
+ | `onPaymentSuccess` | `(txId: string) => void` | ❌ | - | Callback on successful payment |
336
+ | `onPaymentError` | `(error: Error) => void` | ❌ | - | Callback on payment error |
337
+ | `onWalletConnect` | `(publicKey: string) => void` | ❌ | - | Callback when wallet connects |
338
+ | `onDisconnect` | `() => void` | ❌ | - | Callback when wallet disconnects |
343
339
 
344
340
  See [full API documentation](./docs/API_REFERENCE.md) for complete reference.
345
341
 
@@ -410,8 +406,8 @@ npm run lint
410
406
 
411
407
  - Make sure you imported both required stylesheets:
412
408
  ```tsx
413
- import "@payai/x402-solana-react/styles";
414
- import "@solana/wallet-adapter-react-ui/styles.css";
409
+ import '@payai/x402-solana-react/styles';
410
+ import '@solana/wallet-adapter-react-ui/styles.css';
415
411
  ```
416
412
  - Check browser console for CSS loading errors
417
413
  - Verify Tailwind CSS is configured if using custom classes
@@ -428,6 +424,7 @@ npm run lint
428
424
  ### Features Complete
429
425
 
430
426
  - ✅ Core paywall component with Solana integration
427
+ - ✅ **x402 Protocol v2** - Full support via `x402-solana`
431
428
  - ✅ Payment processing via x402 protocol
432
429
  - ✅ Multi-wallet support (Phantom, Solflare, etc.)
433
430
  - ✅ Beautiful Solana-themed UI with Tailwind CSS
@@ -435,6 +432,18 @@ npm run lint
435
432
  - ✅ Devnet integration with PayAI facilitator
436
433
  - ✅ Responsive design and accessibility
437
434
 
435
+ ### x402 v2 Protocol
436
+
437
+ This package supports the x402 v2 specification which includes:
438
+
439
+ | Feature | v1 | v2 |
440
+ | ------------------ | ------------------------- | ------------------------------ |
441
+ | **Network Format** | `solana`, `solana-devnet` | CAIP-2 format (auto-converted) |
442
+ | **Payment Header** | `X-PAYMENT` | `PAYMENT-SIGNATURE` |
443
+ | **Amount Field** | `maxAmountRequired` | `amount` |
444
+
445
+ **Note**: You can still use simple network names (`solana`, `solana-devnet`) in your code - the library automatically converts them to CAIP-2 format internally.
446
+
438
447
  ## 🤝 Contributing
439
448
 
440
449
  This project is currently in early development. Contributions welcome!
@@ -445,9 +454,9 @@ MIT License
445
454
 
446
455
  ## 🔗 Related Projects
447
456
 
448
- - [x402-solana](https://github.com/payainetwork/x402-solana) - Base Solana payment protocol implementation
449
- - [x402](https://github.com/payainetwork/x402) - Core x402 payment protocol
450
- - [PayAI Network](https://payai.network) - x402 payment infrastructure
457
+ - [x402-solana](https://www.npmjs.com/package/x402-solana) - Base Solana payment protocol implementation (x402 v2)
458
+ - [x402](https://github.com/coinbase/x402) - Core x402 payment protocol specification
459
+ - [PayAI Network](https://payai.network) - x402 payment infrastructure and facilitator
451
460
 
452
461
  ---
453
462
 
package/dist/hooks/useX402Payment.d.ts CHANGED
@@ -5,7 +5,8 @@ export interface PaymentConfig {
5
5
  rpcUrl?: string;
6
6
  apiEndpoint?: string;
7
7
  facilitatorUrl?: string;
8
- maxPaymentAmount?: number;
8
+ /** Maximum payment amount in USDC (V2 protocol) */
9
+ amount?: number;
9
10
  /** Enable verbose logging for debugging (default: false) */
10
11
  verbose?: boolean;
11
12
  }
package/dist/hooks/useX402Payment.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"useX402Payment.d.ts","sourceRoot":"","sources":["../../src/hooks/useX402Payment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,oBAAoB,CA6J1E"}
1
+ {"version":3,"file":"useX402Payment.d.ts","sourceRoot":"","sources":["../../src/hooks/useX402Payment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0DAA0D;IAC1D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,oBAAoB,CAyJ1E"}