@x402-iota/react

React components and hooks for x402 payment handling in web applications.

Overview

Production-ready React components for:

• Payment UI dialogs
• Payment status indicators
• Automatic 402 handling
• Custom hooks for payment logic

Installation

npm install @x402-iota/react @x402-iota/client @x402-iota/core ethers

Quick Start

Setup Provider

"use client"; // Next.js App Router

import { X402Provider } from "@x402-iota/react";
import { X402Client } from "@x402-iota/client";

export default function App() {
  const client = new X402Client({ signer: wallet, network });

  return (
    <X402Provider
      client={client}
      signer={wallet}
      network="iota-evm-testnet"
      facilitatorUrl="http://localhost:3001"
    >
      <YourApp />
    </X402Provider>
  );
}

Use Payment Dialog

"use client";

import { useState } from "react";
import { useX402Request, PaymentDialog } from "@x402-iota/react";

export default function ProtectedContent() {
  const [isOpen, setIsOpen] = useState(false);
  const [payment, setPayment] = useState(null);

  const request = useX402Request({
    url: "/api/protected",
    method: "GET",
  });

  const handleClick = async () => {
    try {
      await request.makeRequest();
    } catch (error: any) {
      if (error.response?.status === 402) {
        setPayment(error.response.data);
        setIsOpen(true);
      }
    }
  };

  return (
    <>
      <button onClick={handleClick}>Get Protected Data</button>

      <PaymentDialog
        isOpen={isOpen}
        response={payment}
        onClose={() => setIsOpen(false)}
        onPaymentSubmit={(header) => request.retryWithPayment(header)}
      />

      {request.data && <div>{JSON.stringify(request.data)}</div>}
    </>
  );
}

Components

PaymentRequired

Display payment requirements.

<PaymentRequired
  response={paymentResponse}
  onPaymentSubmit={handlePaymentSubmit}
  isLoading={isLoading}
  error={error}
/>

PaymentDialog

Modal dialog for payment flow.

<PaymentDialog
  isOpen={isOpen}
  response={paymentResponse}
  onClose={handleClose}
  onPaymentSubmit={handlePaymentSubmit}
/>

PaymentStatus

Show payment status (loading/success/error).

<PaymentStatus
  status={status}
  error={error}
  txHash={txHash}
  onRetry={handleRetry}
  onDismiss={handleDismiss}
/>

Hooks

useX402Request

Automatically handle 402 payments.

const { data, loading, error, paymentRequired, retryWithPayment, makeRequest } =
  useX402Request({
    url: "/api/data",
    method: "GET",
  });

usePaymentSigner

Sign payment with wallet.

const { signPayment, status, error, txHash } = usePaymentSigner({
  paymentRequirements: requirement,
  onSuccess: (header) => console.log("Signed!"),
  onError: (err) => console.error(err),
});

await signPayment();

usePaymentStatus

Manage payment status state.

const { status, error, txHash, setLoading, setSuccess, setError, reset } =
  usePaymentStatus();

Styling

Default professional styles included. Customize with CSS:

/* Override default styles */
.x402-approve-btn {
  background-color: #your-color;
}

.x402-dialog {
  border-radius: 12px;
}

Related Packages

• @x402-iota/client - Client SDK
• @x402-iota/core - Core types
• @x402-iota/server-express - Express middleware
• @x402-iota/server-nextjs - Next.js middleware

License

MIT