whalebox-news-sdk

WhaleBox.NEWS payment SDK - Add time-priced content monetization to any frontend.

Features

• Multi-chain support: Works on Base, Ethereum, Arbitrum, Optimism, Polygon, and Avalanche
• Multi-stablecoin: Support for both USDC and USDT
• Built-in token swap: Integrated Uniswap for converting any token to stablecoins
• Time-based pricing: Content prices increase with age (Fresh → Aging → Stale)
• Instant unlocks: Off-chain commits via Yellow/Nitrolite for instant UX
• Batched settlement: On-chain settlement happens when session ends
• Drop-in components: Ready-to-use React components with chain/currency selectors
• Wallet integration: RainbowKit + Wagmi for seamless wallet connection

Pricing Tiers

| Tier | Days | Multiplier | Price (base $50) | |------|------|------------|------------------| | Fresh | 0-10 | 10x | $500 | | Aging | 11-30 | 30x | $1,500 | | Stale | 31+ | 1000x | $50,000 |

Installation

npm install whalebox-news-sdk @rainbow-me/rainbowkit @tanstack/react-query wagmi viem

Quick Start

import { WhaleBoxProvider, SessionWidget, PaywallGate } from 'whalebox-news-sdk';
import '@rainbow-me/rainbowkit/styles.css';

function App() {
  return (
    <WhaleBoxProvider>
      {/* Session widget - place in your sidebar or header */}
      <SessionWidget />

      {/* Wrap premium content with PaywallGate */}
      <PaywallGate
        contentId="article-123"
        title="Breaking: Major Market Movement"
        createdDate="2024-01-15"
      >
        <article>
          <h1>Premium Content</h1>
          <p>This content is only visible after purchase...</p>
        </article>
      </PaywallGate>
    </WhaleBoxProvider>
  );
}

Components

WhaleBoxProvider

Wraps your app with all necessary providers (Wagmi, RainbowKit, QueryClient).

<WhaleBoxProvider
  config={{
    walletConnectProjectId: 'your-project-id', // Get from cloud.walletconnect.com
    theme: 'dark', // or 'light'
    accentColor: '#7c5cff',
    defaultBudget: 5000,
    defaultChainId: 8453, // Base mainnet (optional)
    defaultStablecoin: 'USDC', // 'USDC' or 'USDT' (optional)
  }}
>
  {children}
</WhaleBoxProvider>

Config Options:

• defaultChainId: Starting chain (e.g., 1 for Ethereum, 8453 for Base)
• defaultStablecoin: Preferred stablecoin - 'USDC' or 'USDT'
• Users can switch chains and stablecoins in the SessionWidget UI

SessionWidget

Drop-in widget for wallet connection and session management.

<SessionWidget
  defaultBudget={5000}
  className="my-custom-class"
  style={{ position: 'fixed', bottom: 20, right: 20 }}
/>

PaywallGate

Wraps content that requires payment.

<PaywallGate
  contentId="unique-content-id"
  title="Content Title"
  createdDate={new Date('2024-01-15')}
  lockedPreview={<BlurredPreview />}
  onPurchaseComplete={() => console.log('Purchased!')}
>
  <PremiumContent />
</PaywallGate>

PriceBadge

Shows price and tier for content listings.

<PriceBadge
  contentId="article-123"
  createdDate="2024-01-15"
  showTier={true}
  size="md" // 'sm' | 'md' | 'lg'
/>

Hooks

useWhaleBoxSession

Access session state and methods directly.

import { useWhaleBoxSession } from 'whalebox-news-sdk';

function MyComponent() {
  const {
    session,                 // { status, balance, spent, purchases, stablecoin }
    isWalletConnected,
    walletAddress,
    chainId,                 // Current chain ID
    selectedStablecoin,      // 'USDC' or 'USDT'
    stablecoinBalance,       // Balance of selected stablecoin
    availableStablecoins,    // ['USDC', 'USDT'] for current chain
    setSelectedStablecoin,   // (stablecoin: 'USDC' | 'USDT') => void
    createSession,           // (budget: number) => Promise<void>
    purchase,                // (contentId, title, price) => Promise<boolean>
    settleSession,           // () => Promise<void>
    resetSession,            // () => void
    isPurchased,             // (contentId: string) => boolean
  } = useWhaleBoxSession();

  // Custom purchase flow
  const handleBuy = async () => {
    const success = await purchase('content-id', 'Title', 500);
    if (success) {
      // Show unlocked content
    }
  };

  // Switch stablecoin
  const switchToUSDT = () => {
    if (availableStablecoins.includes('USDT')) {
      setSelectedStablecoin('USDT');
    }
  };
}

Pricing Utilities

import {
  calculatePrice,
  formatPrice,
  getFreshnessTier,
  getUrgencyMessage,
} from 'whalebox-news-sdk';

const { price, tier, daysSince, multiplier } = calculatePrice('2024-01-15');
console.log(formatPrice(price)); // "$500.00"
console.log(tier.name); // "fresh"
console.log(getUrgencyMessage(tier, daysSince)); // "7 days until price increases to 30x"

Supported Networks & Stablecoins

| Network | Chain ID | USDC | USDT | |---------|----------|------|------| | Ethereum | 1 | ✅ | ✅ | | Base | 8453 | ✅ | ✅ | | Base Sepolia (testnet) | 84532 | ✅ | ❌ | | Arbitrum One | 42161 | ✅ | ✅ | | Optimism | 10 | ✅ | ✅ | | Polygon | 137 | ✅ | ✅ | | Avalanche C-Chain | 43114 | ✅ | ✅ |

Base Sepolia Testnet Contracts

| Contract | Address | |----------|---------| | NEWS Token | 0xabfeAfa4F66a06F4Dfb19CbE3072AAdf1e5e034A | | NewsVault | 0xdd078036fb2D5E966C11B5894effe9B189049c8d | | USDC | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |

Documentation

• Getting Started - 5-minute integration guide
• Hooks Reference - Advanced usage with hooks
• Pricing Model - Understanding freshness-based pricing
• Styling Guide - Customizing component appearance
• Publishing - npm publishing guide

How It Works

1. User connects wallet via RainbowKit (supports all major chains)
2. User selects chain & stablecoin - Choose from Ethereum, Base, Arbitrum, etc. and USDC/USDT
3. User creates a session with stablecoin budget (approved to NewsVault)
4. User unlocks content - instant off-chain commits (Yellow/Nitrolite style)
5. User settles session - all purchases recorded on-chain in batch

This gives instant UX while maintaining on-chain settlement for proof of purchase.

Chain Switching

Users can switch between supported chains using:

• The SessionWidget's built-in network selector
• Their wallet's network switcher
• The useSwitchChain() hook from wagmi

Stablecoin selection automatically updates based on what's available on the current chain.

Token Swapping

Don't have USDC or USDT? No problem!

The SDK includes built-in Uniswap integration that lets users swap any token for stablecoins:

• Auto-detection: Swap button appears when stablecoin balance is zero
• Popular tokens: Quick access to ETH, WBTC, and other major tokens
• Real-time quotes: See estimated output before swapping
• One-click: Approve + swap in a single flow
• DEX routing: Uses Uniswap V2 routers on each chain for best liquidity

Supported swap protocols by chain:

• Ethereum: Uniswap V2
• Base: BaseSwap
• Arbitrum: SushiSwap
• Optimism: Velodrome
• Polygon: QuickSwap
• Avalanche: Trader Joe

Users can swap ETH, native tokens, or any ERC20 directly to USDC/USDT without leaving your app!

License

MIT