@onchainfi/hyperlink

Turn any text into a payment link. One click, instant x402 payments.

<p>
  Enjoyed this article? 
  <PaymentLink to="0x..." amount="0.50">
    Buy me a coffee ☕
  </PaymentLink>
</p>

Features

• 💸 One-Click Payments - Text links that trigger instant payments
• 🎨 Looks Like Text - Seamlessly integrates into content
• ✅ Confirmation Modal - Shows payment details before executing
• 🔗 Shareable Links - Generate payment URLs to share anywhere
• 🚀 Zero Navigation - Payments happen inline, no page changes
• 🔐 Built on Connect - Uses @onchainfi/connect for wallet + payments

Installation

npm install @onchainfi/hyperlink @onchainfi/connect

Prerequisites: Requires @onchainfi/connect to be installed and configured.

Quick Start

1. Set Up Connect (if not already done)

import { OnchainConnect } from '@onchainfi/connect';

<OnchainConnect privyAppId="..." onchainApiKey="...">
  <App />
</OnchainConnect>

2. Use PaymentLink Anywhere

import { PaymentLink } from '@onchainfi/hyperlink';

export default function BlogPost() {
  return (
    <article>
      <h1>My Article</h1>
      <p>Great content here...</p>
      
      <p>
        Enjoyed this? 
        <PaymentLink 
          to="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
          amount="0.50"
        >
          Buy me a coffee ☕
        </PaymentLink>
      </p>
    </article>
  );
}

That's it! Users click the link, see a confirmation modal, approve, and payment completes - all without leaving the page.

API Reference

<PaymentLink>

A text link that triggers an inline payment.

Props:

{
  // Required
  to: string;        // Recipient address
  amount: string;    // Amount in token units
  children: ReactNode;  // Link text
  
  // Optional
  network?: string;     // Default: 'base'
  token?: string;       // Default: 'USDC'
  memo?: string;        // Payment description
  priority?: 'speed' | 'cost' | 'reliability' | 'balanced';
  className?: string;   // Custom link styling
  
  // Callbacks
  onSuccess?: (txHash: string) => void;
  onError?: (error: Error) => void;
  
  // Behavior
  confirmMessage?: string;  // Custom confirmation text
  skipConfirm?: boolean;    // Skip modal, pay immediately
  disabled?: boolean;
}

Example:

<PaymentLink
  to="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  amount="1.00"
  memo="Premium article access"
  onSuccess={(txHash) => unlockContent()}
>
  Unlock for $1
</PaymentLink>

createPaymentLink()

Generate shareable payment URLs.

import { createPaymentLink } from '@onchainfi/hyperlink';

const link = createPaymentLink({
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  amount: '0.50',
  memo: 'Coffee donation',
  baseUrl: 'https://myblog.com/donate'
});

// Returns: https://myblog.com/donate?x402=eyJ0b...

Options:

{
  to: string;
  amount: string;
  network?: string;
  token?: string;
  memo?: string;
  priority?: string;
  baseUrl?: string;    // URL to append payment data to
  useHash?: boolean;   // Use hash fragment instead of query param
}

Use Cases

Content Paywalls

function PremiumArticle() {
  const [unlocked, setUnlocked] = useState(false);
  
  if (!unlocked) {
    return (
      <div>
        <h2>Premium Content</h2>
        <p>
          <PaymentLink 
            to="0x..." 
            amount="0.10"
            onSuccess={() => setUnlocked(true)}
          >
            Pay $0.10 to unlock
          </PaymentLink>
        </p>
      </div>
    );
  }
  
  return <Article />;
}

Creator Tips

function CreatorProfile() {
  return (
    <div>
      <h1>@creator</h1>
      <p>
        Support my work: 
        <PaymentLink to="0x..." amount="1.00">$1</PaymentLink> | 
        <PaymentLink to="0x..." amount="5.00">$5</PaymentLink> | 
        <PaymentLink to="0x..." amount="10.00">$10</PaymentLink>
      </p>
    </div>
  );
}

Donation Buttons

<footer>
  <p>
    This site is free. If you found it helpful, consider
    <PaymentLink to="0x..." amount="0.50" memo="Site donation">
      donating
    </PaymentLink>
    to keep it running.
  </p>
</footer>

Shareable Payment Links

function ShareDonationLink() {
  const link = createPaymentLink({
    to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    amount: '0.50',
    memo: 'Support the project',
    baseUrl: 'https://myproject.com'
  });
  
  return (
    <button onClick={() => navigator.clipboard.writeText(link)}>
      Copy Donation Link
    </button>
  );
}

Styling

PaymentLink accepts className for custom styling:

<PaymentLink 
  to="0x..." 
  amount="0.10"
  className="font-bold text-blue-500 hover:text-blue-400"
>
  Custom styled link
</PaymentLink>

Default style: Purple link with underline (matches Onchain aesthetic)

Advanced Features

Skip Confirmation (Instant Payment)

<PaymentLink 
  to="0x..." 
  amount="0.01" 
  skipConfirm={true}
>
  Quick tip $0.01
</PaymentLink>

Custom Confirmation Message

<PaymentLink
  to="0x..."
  amount="5.00"
  confirmMessage="This will unlock premium features for 30 days"
>
  Upgrade to Premium
</PaymentLink>

Payment Callbacks

<PaymentLink
  to="0x..."
  amount="0.50"
  onSuccess={(txHash) => {
    console.log('Payment sent!', txHash);
    // Unlock content, track analytics, etc.
  }}
  onError={(error) => {
    console.error('Payment failed:', error);
    // Show error message, log for support
  }}
>
  Pay here
</PaymentLink>

How It Works

1. User clicks the payment link
2. Modal shows payment details (amount, recipient, network)
3. User confirms
4. Connect wallet handles signature + payment
5. Payment routes through Onchain aggregator
6. Success! User stays on the same page

All payments flow through api.onchain.fi - same infrastructure as Connect.

Requirements

• ✅ @onchainfi/connect installed and configured
• ✅ User has Connect wallet connected
• ✅ Sufficient token balance

TypeScript

Fully typed:

import type { 
  PaymentLinkProps,
  PaymentLinkData,
  CreatePaymentLinkOptions 
} from '@onchainfi/hyperlink';

Examples

See examples/ folder for complete working examples:

• Content paywall
• Tip buttons
• Donation links
• Shopping cart integration

License

AGPL-3.0

Links

• Documentation
• GitHub
• npm
• Connect Package

Support

• Email: dev@onchain.fi
• GitHub Issues: github.com/onchainfi/hyperlink/issues