feat: add Arkade Checkout example app with Lightning payment integration

- Created a new Next.js app for Arkade Checkout example.
- Implemented root layout and home page with a "Buy Me a Coffee" feature.
- Added success page to confirm payment completion.
- Integrated CheckoutModal component for handling payment interactions.
- Configured Next.js with Arkade Checkout plugin and necessary environment settings.
- Established API routes for creating and claiming payments.
- Developed client-side components for checkout and payment status.
- Implemented Verifiable Secret Sharing (VSS) for secure private key management.
- Added CLI tool for generating credentials and configuration.
- Documented setup and usage instructions in README and VSS setup guide.

Author: tiero

apps/checkout-example/.env.example

@@ -0,0 +1,19 @@
+# Arkade Checkout Configuration
+# Run `npx create-arkade-checkout` to generate these values automatically
+
+# Your Arkade private key (generated by create-arkade-checkout)
+ARKADE_PRIVATE_KEY_HEX=your_private_key_here
+
+# Production (Mainnet) - Default
+ARKADE_SERVER_URL=https://arkade.computer
+BOLTZ_API_URL=https://api.ark.boltz.exchange
+ARKADE_NETWORK=bitcoin
+
+# Development (Testnet) - Uncomment to use testnet
+# ARKADE_SERVER_URL=https://mutinynet.arkade.sh
+# BOLTZ_API_URL=https://api.boltz.mutinynet.arkade.sh
+# ARKADE_NETWORK=mutinynet
+
+# Optional: Vercel KV for persistent storage (recommended for production)
+# KV_REST_API_URL=your_vercel_kv_url
+# KV_REST_API_TOKEN=your_vercel_kv_token

apps/checkout-example/README.md

@@ -0,0 +1,301 @@
+# Arkade Checkout Example
+
+A complete Next.js example demonstrating how to integrate Bitcoin Lightning payments using `@arkade-os/checkout`.
+
+## Features
+
+- 💳 Multiple pricing tiers with USD conversion
+- ⚡ Lightning Network payments via Arkade + Boltz
+- 🎨 Beautiful, responsive UI
+- 📱 Mobile-friendly checkout experience
+- ✨ Real-time payment status updates
+- 🔄 Automatic redirect after successful payment
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+### 2. Generate Credentials
+
+```bash
+npx create-arkade-checkout
+```
+
+This will create a `.env.local` file with your private key and configuration.
+
+### 3. Run Development Server
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+yarn dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Project Structure
+
+```
+example/
+├── app/
+│   ├── api/
+│   │   └── arkade/
+│   │       └── [[...path]]/
+│   │           └── route.ts          # Unified API handler
+│   ├── checkout/
+│   │   └── [id]/
+│   │       └── page.tsx              # Checkout page with QR code
+│   ├── success/
+│   │   └── page.tsx                  # Success page after payment
+│   ├── layout.tsx                    # Root layout
+│   ├── page.tsx                      # Home page with examples
+│   └── globals.css                   # Global styles
+├── public/                           # Static files
+├── .env.example                      # Environment variables template
+├── next.config.mjs                   # Next.js config with Arkade plugin
+├── package.json
+└── tsconfig.json
+```
+
+## Environment Variables
+
+Create a `.env.local` file (automatically generated by `npx create-arkade-checkout`):
+
+```env
+# Your Arkade private key
+ARKADE_PRIVATE_KEY_HEX=your_private_key
+
+# Production (Mainnet) - Default
+ARKADE_SERVER_URL=https://arkade.computer
+BOLTZ_API_URL=https://api.ark.boltz.exchange
+ARKADE_NETWORK=bitcoin
+
+# Development (Testnet)
+# ARKADE_SERVER_URL=https://mutinynet.arkade.sh
+# BOLTZ_API_URL=https://api.boltz.mutinynet.arkade.sh
+# ARKADE_NETWORK=mutinynet
+
+# Optional: Vercel KV for production
+# KV_REST_API_URL=your_vercel_kv_url
+# KV_REST_API_TOKEN=your_vercel_kv_token
+```
+
+## Usage Examples
+
+### Basic Purchase Button
+
+```tsx
+"use client";
+import { useCheckout } from "@arkade-os/checkout";
+
+export default function BuyButton() {
+  const { navigate, isNavigating } = useCheckout();
+
+  return (
+    <button
+      onClick={() =>
+        navigate({
+          title: "Premium Plan",
+          description: "1 year subscription",
+          amount: 50,
+          currency: "USD",
+          metadata: { successUrl: "/success" },
+        })
+      }
+      disabled={isNavigating}
+    >
+      Buy Now
+    </button>
+  );
+}
+```
+
+### With BTC Amount
+
+```tsx
+navigate({
+  title: "Premium eBook",
+  description: "Digital download",
+  amount: 0.001,
+  currency: "BTC",
+  metadata: { successUrl: "/success" },
+});
+```
+
+### With Satoshis
+
+```tsx
+navigate({
+  title: "Donation",
+  description: "Support our work",
+  amount: 10000,
+  currency: "SAT",
+  metadata: { successUrl: "/success" },
+});
+```
+
+### Custom Metadata
+
+```tsx
+navigate({
+  title: "Product Purchase",
+  description: "Premium widget",
+  amount: 25,
+  currency: "USD",
+  metadata: {
+    successUrl: "/success",
+    productId: "widget-123",
+    customerId: "user-456",
+    tier: "premium",
+  },
+});
+```
+
+## How It Works
+
+1. **User clicks "Buy Now"** → `useCheckout().navigate()` is called
+2. **Create checkout** → POST to `/api/arkade/create` with payment details
+3. **Redirect to checkout** → User sees QR code at `/checkout/[id]`
+4. **Payment polling** → Frontend polls `/api/arkade/status?id=[id]`
+5. **Background claim** → Server waits for payment via `/api/arkade/claim`
+6. **Success redirect** → User redirected to `successUrl` after payment
+
+## API Routes
+
+The example uses the unified route handler that provides:
+
+- `POST /api/arkade/create` - Create new checkout session
+- `POST /api/arkade/claim` - Start background payment claim process
+- `GET /api/arkade/status?id=[id]` - Check payment status
+
+## Customization
+
+### Styling
+
+The example includes comprehensive CSS in [app/globals.css](app/globals.css). You can:
+
+- Modify CSS variables in `:root` for colors and spacing
+- Override `.arkade-checkout-*` classes for widget styling
+- Use Tailwind CSS or any other styling solution
+
+### Checkout Component
+
+The checkout page uses the pre-built `<Checkout />` component, but you can create your own:
+
+```tsx
+"use client";
+import { useState, useEffect } from "react";
+
+export default function CustomCheckout({ id }: { id: string }) {
+  const [checkout, setCheckout] = useState(null);
+
+  useEffect(() => {
+    fetch(`/api/arkade/status?id=${id}`)
+      .then((res) => res.json())
+      .then(setCheckout);
+  }, [id]);
+
+  // Build your custom UI with checkout data
+  return <div>{/* Your custom checkout UI */}</div>;
+}
+```
+
+## Testing
+
+### Test Payments
+
+For development/testing:
+
+1. Use testnet configuration in `.env.local`
+2. Get testnet Bitcoin from a faucet
+3. Use a Lightning testnet wallet (Phoenix, Breez, etc.)
+
+### Production Checklist
+
+- [ ] Environment variables set for mainnet
+- [ ] Vercel KV configured (recommended)
+- [ ] Test with small amounts first
+- [ ] Verify webhook/success URLs are correct
+- [ ] Check server function timeout (5min+ recommended)
+
+## Deployment
+
+### Deploy to Vercel
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new)
+
+1. Push to GitHub
+2. Import to Vercel
+3. Add environment variables:
+   - `ARKADE_PRIVATE_KEY_HEX`
+   - `ARKADE_SERVER_URL`
+   - `BOLTZ_API_URL`
+   - `ARKADE_NETWORK`
+4. Optionally configure Vercel KV for storage
+5. Deploy!
+
+### Other Platforms
+
+The example works on any platform that supports Next.js:
+
+- Netlify
+- Cloudflare Pages
+- Railway
+- Self-hosted
+
+Make sure your platform supports:
+
+- Next.js 15+
+- Server-side functions
+- Long-running functions (5min timeout for payment claims)
+
+## Troubleshooting
+
+### "Private key not found"
+
+Run `npx create-arkade-checkout` to generate `.env.local`
+
+### Checkout not found after restart
+
+Using in-memory storage. For production, configure Vercel KV in environment variables.
+
+### Payments not claiming
+
+Check:
+
+- Private key has sufficient balance for swap fees
+- Correct Boltz API URL for your network
+- Server function timeout is at least 5 minutes
+
+### Module not found errors
+
+If you see import errors, make sure you're in a workspace setup or adjust the import to use the published package:
+
+```tsx
+// In workspace (this example)
+import { useCheckout } from "@arkade-os/checkout";
+
+// With published package
+import { useCheckout } from "@arkade-os/checkout";
+```
+
+## Learn More
+
+- [Arkade SDK Documentation](https://github.com/arkade-os/sdk)
+- [Boltz Documentation](https://docs.boltz.exchange)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Lightning Network](https://lightning.network)
+
+## License
+
+MIT