@goplausible/openclaw-algorand-plugin 0.5.0

package/skills/algorand-x402-typescript/references/create-typescript-x402-paywall-reference.md

@@ -0,0 +1,323 @@
+# x402 Paywall Reference
+
+Detailed API reference for `@x402-avm/paywall` and framework middleware packages.
+
+## Package: @x402-avm/paywall
+
+### Installation
+
+```bash
+npm install @x402-avm/paywall @x402-avm/avm @x402-avm/core
+```
+
+### Exports from @x402-avm/paywall
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `createPaywall` | Function | Creates a new `PaywallBuilder` instance |
+| `PaywallBuilder` | Class | Builder for configuring and building paywall providers |
+| `avmPaywall` | Object | AVM network handler (algorand:*) |
+| `evmPaywall` | Object | EVM network handler (eip155:*) |
+| `svmPaywall` | Object | SVM network handler (solana:*) |
+| `PaywallProvider` | Type | Interface for paywall HTML generation |
+| `PaywallConfig` | Type | Configuration options for paywall branding |
+| `PaywallNetworkHandler` | Type | Interface for network-specific handlers |
+| `PaymentRequired` | Type | 402 response structure |
+| `PaymentRequirements` | Type | Individual payment requirement |
+
+### Exports from @x402-avm/paywall/avm
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `avmPaywall` | Object | AVM paywall handler (same as main export) |
+
+---
+
+## PaywallBuilder
+
+### createPaywall()
+
+Factory function that creates a new `PaywallBuilder` instance.
+
+```typescript
+function createPaywall(): PaywallBuilder;
+```
+
+### PaywallBuilder Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `.withNetwork(handler)` | `(handler: PaywallNetworkHandler) => PaywallBuilder` | Register a network-specific paywall handler. Order matters -- first match wins. |
+| `.withConfig(config)` | `(config: PaywallConfig) => PaywallBuilder` | Set default paywall configuration. |
+| `.build()` | `() => PaywallProvider` | Build and return a `PaywallProvider`. |
+
+### PaywallProvider
+
+```typescript
+interface PaywallProvider {
+  /**
+   * Generate an HTML paywall page for the given payment requirements.
+   * @param paymentRequired - The full 402 response from the server
+   * @param config - Optional runtime config override
+   * @returns Full HTML page as a string
+   */
+  generateHtml(paymentRequired: PaymentRequired, config?: PaywallConfig): string;
+}
+```
+
+### PaywallConfig
+
+```typescript
+interface PaywallConfig {
+  /** App name shown in wallet connection modal title */
+  appName?: string;
+  /** App logo URL shown in the paywall header */
+  appLogo?: string;
+  /** URL of the content being accessed (used for retry after payment) */
+  currentUrl?: string;
+  /** Whether to use testnet (default: true) */
+  testnet?: boolean;
+}
+```
+
+---
+
+## PaywallNetworkHandler
+
+Interface for creating custom network-specific paywall handlers.
+
+```typescript
+interface PaywallNetworkHandler {
+  /**
+   * Check if this handler supports the given payment requirement.
+   * @param requirement - A single payment requirement from the 402 response
+   * @returns true if this handler can generate HTML for this requirement
+   */
+  supports(requirement: PaymentRequirements): boolean;
+
+  /**
+   * Generate the full HTML paywall page.
+   * @param requirement - The matched payment requirement
+   * @param paymentRequired - The full PaymentRequired response
+   * @param config - Paywall configuration
+   * @returns Full HTML page as a string
+   */
+  generateHtml(
+    requirement: PaymentRequirements,
+    paymentRequired: PaymentRequired,
+    config: PaywallConfig,
+  ): string;
+}
+```
+
+### Built-in Handlers
+
+| Handler | Supports | Networks |
+|---------|----------|----------|
+| `avmPaywall` | `network.startsWith("algorand:")` | Algorand Testnet, Algorand Mainnet |
+| `evmPaywall` | `network.startsWith("eip155:")` | Base, Ethereum, etc. |
+| `svmPaywall` | `network.startsWith("solana:")` | Solana |
+
+### Handler Selection
+
+When `PaywallProvider.generateHtml()` is called, it iterates through registered handlers in order. The first handler whose `supports()` returns true for any of the `accepts` requirements is used to generate the HTML.
+
+---
+
+## avmPaywall Handler
+
+The `avmPaywall` handler generates a full React-based HTML page with:
+
+1. **window.x402 global** -- Embeds payment configuration for the client-side app
+2. **Wallet discovery** -- Uses `@wallet-standard/app` to find Algorand wallets
+3. **Wallet selection UI** -- Dropdown with icons for detected wallets
+4. **Balance checking** -- Reads USDC ASA balance for the connected account
+5. **Transaction signing** -- Uses `algorand:signTransaction` wallet-standard feature
+6. **Payment submission** -- Retries original request with `PAYMENT-SIGNATURE` header
+7. **Automatic redirect** -- Redirects to paid content after successful payment
+
+### Supported Wallets
+
+| Wallet | Type | Feature |
+|--------|------|---------|
+| Pera Wallet | Mobile + WalletConnect | `algorand:signTransaction` |
+| Defly Wallet | Mobile + WalletConnect | `algorand:signTransaction` |
+| Lute Wallet | Browser Extension | `algorand:signTransaction` |
+
+### window.x402 Configuration Object
+
+The generated HTML page injects this configuration:
+
+```javascript
+window.x402 = {
+  amount: 0.01,           // Amount in USDC (human-readable)
+  paymentRequired: {...},  // Full PaymentRequired response
+  testnet: true,           // Network mode
+  currentUrl: "...",       // URL to retry after payment
+  config: { chainConfig: {} },
+  appName: "My App",
+  appLogo: "https://...",
+};
+```
+
+---
+
+## Framework Middleware
+
+### @x402-avm/express
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `paymentMiddleware` | `(routes, server, config?, paywall?)` | Express middleware |
+| `paymentMiddlewareFromHTTPServer` | `(httpServer, config?, paywall?)` | Express middleware from HTTP server |
+| `paymentMiddlewareFromConfig` | `(routes, facilitator?, schemes?, config?, paywall?)` | Express middleware from config |
+| `x402ResourceServer` | Class | Resource server for facilitator communication |
+| `x402HTTPResourceServer` | Class | HTTP-aware resource server with route config |
+
+### @x402-avm/hono
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `paymentMiddleware` | `(routes, server, config?, paywall?)` | Hono middleware |
+| `paymentMiddlewareFromHTTPServer` | `(httpServer, config?, paywall?)` | Hono middleware from HTTP server |
+| `paymentMiddlewareFromConfig` | `(routes, facilitator?, schemes?, config?, paywall?)` | Hono middleware from config |
+| `x402ResourceServer` | Class | Resource server for facilitator communication |
+
+### @x402-avm/next
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `paymentProxy` | `(routes, server, config?, paywall?)` | Next.js middleware proxy |
+| `withX402` | `(handler, routeConfig, server, config?, paywall?)` | Next.js route wrapper |
+| `paymentProxyFromHTTPServer` | `(httpServer, config?, paywall?)` | Next.js proxy from HTTP server |
+| `paymentProxyFromConfig` | `(routes, facilitator?, schemes?, config?, paywall?)` | Next.js proxy from config |
+| `x402ResourceServer` | Class | Resource server for facilitator communication |
+
+---
+
+## Route Configuration
+
+```typescript
+interface RouteConfig {
+  [path: string]: {
+    /** Payment requirements -- single object or array for multi-network */
+    accepts: PaymentAccepts | PaymentAccepts[];
+    /** Human-readable description of the resource */
+    description: string;
+    /** MIME type of the response */
+    mimeType: string;
+  };
+}
+
+interface PaymentAccepts {
+  /** Payment scheme (currently "exact") */
+  scheme: string;
+  /** CAIP-2 network identifier */
+  network: string;
+  /** Asset identifier (ASA ID for Algorand, contract address for EVM) */
+  asset: string;
+  /** Receiver address */
+  payTo: string;
+  /** Price string (e.g., "$0.01") */
+  price: string;
+  /** Maximum timeout in seconds for payment validity */
+  maxTimeoutSeconds: number;
+}
+```
+
+---
+
+## Bundle Sizes
+
+The paywall system is designed for tree-shaking. Import only the network handlers you need:
+
+```typescript
+// AVM only -- smallest bundle
+import { avmPaywall } from "@x402-avm/paywall/avm";
+
+// AVM + EVM
+import { avmPaywall, evmPaywall } from "@x402-avm/paywall";
+
+// All networks
+import { avmPaywall, evmPaywall, svmPaywall } from "@x402-avm/paywall";
+```
+
+---
+
+## USDC Asset IDs
+
+| Network | ASA ID | CAIP-2 |
+|---------|--------|--------|
+| Algorand Testnet | `10458941` | `algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=` |
+| Algorand Mainnet | `31566704` | `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=` |
+
+---
+
+## Testing
+
+### Testing the Paywall HTML Generation
+
+```typescript
+import { createPaywall, avmPaywall } from "@x402-avm/paywall";
+
+const paywall = createPaywall()
+  .withNetwork(avmPaywall)
+  .withConfig({ appName: "Test App", testnet: true })
+  .build();
+
+const html = paywall.generateHtml({
+  x402Version: 2,
+  accepts: [{
+    scheme: "exact",
+    network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+    asset: "10458941",
+    payTo: "TEST_ADDRESS",
+    amount: "10000",
+    maxTimeoutSeconds: 300,
+  }],
+  resource: {
+    url: "https://test.example.com/premium",
+    description: "Test content",
+    mimeType: "application/json",
+  },
+});
+
+// Verify the HTML contains expected elements
+console.assert(html.includes("window.x402"));
+console.assert(html.includes("Test App"));
+```
+
+### Testing Middleware Integration
+
+```bash
+# Start server
+npm start
+
+# Test JSON 402 response (API client)
+curl -H "Accept: application/json" http://localhost:3000/api/premium
+
+# Test HTML paywall (browser-like)
+curl -H "Accept: text/html" http://localhost:3000/api/premium
+
+# Test with payment header (after obtaining one)
+curl -H "PAYMENT-SIGNATURE: <base64-payload>" http://localhost:3000/api/premium
+```
+
+---
+
+## Important Notes
+
+- The paywall HTML page is a self-contained React application served inline. No additional static files or CDN dependencies are required.
+- `withNetwork()` order determines handler priority. Register your preferred network first.
+- The `testnet` flag in `PaywallConfig` affects which Algod endpoint the paywall page connects to (AlgoNode testnet vs mainnet).
+- Route paths support Express-style patterns (`:param`, `*` wildcards).
+- The `price` field in route config accepts human-readable strings like `"$0.01"` which are converted to microunits internally.
+
+---
+
+## External Resources
+
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402-avm Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)
+- [@wallet-standard/app](https://github.com/wallet-standard/wallet-standard)
+- [@txnlab/use-wallet](https://txnlab.gitbook.io/use-wallet)

package/skills/algorand-x402-typescript/references/create-typescript-x402-paywall.md

@@ -0,0 +1,281 @@
+# Creating Paywall UIs for x402-Protected Endpoints
+
+Build server-side middleware that serves payment HTML pages to browsers and JSON 402 responses to API clients, with automatic wallet integration for Algorand (Pera, Defly, Lute).
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **A backend framework** (Express.js, Hono, or Next.js)
+2. **A facilitator service** running and accessible via URL
+3. **An Algorand address** to receive payments (payTo address)
+
+## Core Workflow: Server-Side Paywall Architecture
+
+The paywall system has two sides. The server middleware detects missing payments and serves either a JSON 402 or an HTML paywall page. The HTML page handles wallet connection, signing, and retry:
+
+```
+Browser Request
+     |
+     v
+[Server Middleware]
+     |
+     +-- Has PAYMENT-SIGNATURE header?
+     |     |
+     |     +-- Yes: Verify payment, settle transaction, return content
+     |     +-- No: Is this a browser request (Accept: text/html)?
+     |           |
+     |           +-- Yes: Return paywall HTML page (402)
+     |           +-- No: Return JSON 402 response
+     |
+     v
+[Paywall HTML Page]
+     |
+     +-- Reads window.x402 config
+     +-- Shows wallet connection UI (Pera/Defly/Lute)
+     +-- User connects wallet and approves payment
+     +-- Retries request with PAYMENT-SIGNATURE header
+     +-- Redirects to paid content
+```
+
+## How to Proceed
+
+### Step 1: Install Dependencies
+
+Server-side packages:
+```bash
+npm install @x402-avm/paywall @x402-avm/avm @x402-avm/core
+```
+
+Plus your framework middleware:
+```bash
+# Express.js
+npm install @x402-avm/express
+
+# Hono
+npm install @x402-avm/hono
+
+# Next.js
+npm install @x402-avm/next
+```
+
+### Step 2: Create the Paywall with PaywallBuilder
+
+The `PaywallBuilder` creates a `PaywallProvider` that generates HTML paywall pages. Register network handlers in priority order -- first match wins:
+
+```typescript
+import { createPaywall, avmPaywall } from "@x402-avm/paywall";
+
+const paywall = createPaywall()
+  .withNetwork(avmPaywall)    // Supports algorand:* networks
+  .withConfig({
+    appName: "My Premium API",
+    appLogo: "https://example.com/logo.png",
+    testnet: true,
+  })
+  .build();
+```
+
+For multi-network support, register multiple handlers:
+
+```typescript
+import { createPaywall, avmPaywall, evmPaywall, svmPaywall } from "@x402-avm/paywall";
+
+const paywall = createPaywall()
+  .withNetwork(avmPaywall)    // algorand:*
+  .withNetwork(evmPaywall)    // eip155:*
+  .withNetwork(svmPaywall)    // solana:*
+  .withConfig({ appName: "Universal Paywall", testnet: true })
+  .build();
+```
+
+### Step 3: Define Protected Routes
+
+Routes specify what payment is required for each endpoint:
+
+```typescript
+const routes = {
+  "/api/premium-content": {
+    accepts: {
+      scheme: "exact",
+      network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+      asset: "10458941",           // USDC ASA ID on testnet
+      payTo: "YOUR_ALGORAND_ADDRESS_HERE",
+      price: "$0.01",             // 0.01 USDC
+      maxTimeoutSeconds: 300,
+    },
+    description: "Access to premium content",
+    mimeType: "application/json",
+  },
+};
+```
+
+### Step 4: Apply Middleware (Express.js)
+
+```typescript
+import express from "express";
+import { paymentMiddleware, x402ResourceServer } from "@x402-avm/express";
+
+const app = express();
+const server = new x402ResourceServer({ url: process.env.FACILITATOR_URL! });
+
+app.use(paymentMiddleware(routes, server, { testnet: true }, paywall));
+
+app.get("/api/premium-content", (req, res) => {
+  res.json({ content: "This is the paid content." });
+});
+
+app.listen(3000);
+```
+
+### Step 4 (Alt): Apply Middleware (Hono)
+
+```typescript
+import { Hono } from "hono";
+import { paymentMiddleware, x402ResourceServer } from "@x402-avm/hono";
+
+const app = new Hono();
+const server = new x402ResourceServer({ url: process.env.FACILITATOR_URL! });
+
+app.use("*", paymentMiddleware(routes, server, { testnet: true }, paywall));
+
+app.get("/api/premium-content", (c) => {
+  return c.json({ content: "Premium content unlocked!" });
+});
+
+export default app;
+```
+
+### Step 4 (Alt): Apply Middleware (Next.js)
+
+**Middleware approach:**
+```typescript
+// middleware.ts
+import { paymentProxy, x402ResourceServer } from "@x402-avm/next";
+
+const server = new x402ResourceServer({ url: process.env.FACILITATOR_URL! });
+const proxy = paymentProxy(routes, server, { testnet: true }, paywall);
+
+export async function middleware(request: NextRequest) {
+  if (request.nextUrl.pathname.startsWith("/api/premium")) {
+    return proxy(request);
+  }
+  return NextResponse.next();
+}
+```
+
+**Route handler approach (withX402):**
+```typescript
+// app/api/premium/route.ts
+import { withX402, x402ResourceServer } from "@x402-avm/next";
+
+const server = new x402ResourceServer({ url: process.env.FACILITATOR_URL! });
+
+async function handler(request: NextRequest) {
+  return NextResponse.json({ content: "Premium content!" });
+}
+
+export const GET = withX402(handler, routeConfig, server, { testnet: true }, paywall);
+```
+
+## Important Rules / Guidelines
+
+1. **Handler order matters** -- `withNetwork()` calls determine priority. The first handler whose `supports()` returns true for a payment requirement is used
+2. **avmPaywall supports `algorand:*`** -- Any network starting with `algorand:` is matched
+3. **Testnet vs Mainnet** -- Set `testnet: true/false` in both `PaywallConfig` and middleware config
+4. **USDC ASA IDs** -- Testnet: `10458941`, Mainnet: `31566704`
+5. **Facilitator URL is required** -- The middleware needs a running facilitator to verify and settle payments
+6. **Tree-shaking** -- Import only the network handlers you need. `avmPaywall` can be imported from `@x402-avm/paywall` or `@x402-avm/paywall/avm`
+7. **Multiple routes** -- Define multiple entries in the routes object, each with its own price, description, and asset
+
+## Wallet Integration
+
+The AVM paywall HTML page uses `@wallet-standard/app` to discover Algorand wallets:
+
+| Wallet | Type | Feature |
+|--------|------|---------|
+| Pera Wallet | Mobile + WalletConnect | `algorand:signTransaction` |
+| Defly Wallet | Mobile + WalletConnect | `algorand:signTransaction` |
+| Lute Wallet | Browser Extension | `algorand:signTransaction` |
+
+The paywall page automatically:
+- Discovers available wallets via wallet-standard
+- Shows a wallet selection UI
+- Checks USDC balance for the connected account
+- Handles transaction signing
+- Retries the original request with the payment header
+- Redirects to the paid content on success
+
+## Multi-Network Paywalls
+
+Accept payments on multiple chains by specifying an array in `accepts`:
+
+```typescript
+const routes = {
+  "/api/premium": {
+    accepts: [
+      {
+        scheme: "exact",
+        network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+        asset: "10458941",
+        payTo: "ALGO_ADDRESS_HERE",
+        price: "$0.01",
+        maxTimeoutSeconds: 300,
+      },
+      {
+        scheme: "exact",
+        network: "eip155:84532",
+        asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        payTo: "0xEVM_ADDRESS_HERE",
+        price: "$0.01",
+        maxTimeoutSeconds: 30,
+      },
+    ],
+    description: "Premium content - pay with USDC on Algorand or Base",
+    mimeType: "application/json",
+  },
+};
+```
+
+## Custom Paywall Handler
+
+If the built-in paywall does not meet your needs, implement a custom `PaywallNetworkHandler`:
+
+```typescript
+import type { PaywallNetworkHandler } from "@x402-avm/paywall";
+
+const customHandler: PaywallNetworkHandler = {
+  supports(requirement) {
+    return requirement.network.startsWith("algorand:");
+  },
+  generateHtml(requirement, paymentRequired, config) {
+    return `<!DOCTYPE html>
+      <html><body>
+        <h1>Pay ${requirement.amount} to access</h1>
+        <script>window.x402 = ${JSON.stringify({ paymentRequired, ...config })};</script>
+      </body></html>`;
+  },
+};
+
+const paywall = createPaywall()
+  .withNetwork(customHandler)
+  .build();
+```
+
+## Common Errors / Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Paywall not shown in browser | Middleware not applied or route not matched | Check route patterns match request paths |
+| JSON 402 returned to browser | Browser not sending `Accept: text/html` | Ensure direct browser navigation, not programmatic fetch |
+| Wallet not detected | Wallet extension not installed | Install Pera, Defly, or Lute wallet |
+| "Insufficient balance" | Account has no USDC | Fund the wallet with USDC on the correct network |
+| Facilitator unreachable | Wrong URL or service down | Verify `FACILITATOR_URL` environment variable |
+| Payment not settling | Facilitator signer not funded | Ensure the facilitator address has ALGO for fees |
+
+## References / Further Reading
+
+- [create-typescript-x402-paywall-reference.md](./create-typescript-x402-paywall-reference.md) - Detailed API reference
+- [create-typescript-x402-paywall-examples.md](./create-typescript-x402-paywall-examples.md) - Complete code examples
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402-avm Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)