@aibtc/mcp-server 1.1.0 → 1.2.0

package/dist/services/scaffold.service.js

@@ -6,6 +6,16 @@ const TOKEN_DECIMALS = {
     sBTC: 8,
     USDCx: 6,
 };
+// Pricing tier amounts (matches x402-api and stx402 patterns)
+const TIER_AMOUNTS = {
+    free: { STX: "0", sBTC: "0", USDCx: "0" },
+    simple: { STX: "0.001", sBTC: "0.000001", USDCx: "0.001" },
+    standard: { STX: "0.001", sBTC: "0.000001", USDCx: "0.001" },
+    ai: { STX: "0.003", sBTC: "0.000003", USDCx: "0.003" },
+    heavy_ai: { STX: "0.01", sBTC: "0.00001", USDCx: "0.01" },
+    storage_read: { STX: "0.0005", sBTC: "0.0000005", USDCx: "0.0005" },
+    storage_write: { STX: "0.001", sBTC: "0.000001", USDCx: "0.001" },
+};
 /**
  * Convert human-readable amount to smallest unit (microSTX, sats, etc.)
  */
@@ -15,27 +25,35 @@ function toSmallestUnit(amount, tokenType) {
     const paddedFraction = fraction.padEnd(decimals, "0").slice(0, decimals);
     return BigInt(whole + paddedFraction).toString();
 }
+/**
+ * Get amount for endpoint based on tier or explicit amount
+ */
+function getEndpointAmount(ep) {
+    if (ep.tier) {
+        return TIER_AMOUNTS[ep.tier][ep.tokenType];
+    }
+    return ep.amount || TIER_AMOUNTS.standard[ep.tokenType];
+}
 /**
  * Generate Hono route code for each endpoint
  */
 function generateEndpointCode(endpoints) {
     return endpoints
         .map((ep) => {
-        const amountSmallest = toSmallestUnit(ep.amount, ep.tokenType);
+        const amount = getEndpointAmount(ep);
+        const amountSmallest = toSmallestUnit(amount, ep.tokenType);
+        const tierComment = ep.tier ? ` (tier: ${ep.tier})` : "";
         // Generate real example logic based on endpoint characteristics
         const exampleLogic = generateExampleLogic(ep);
         return `
-// ${ep.description}
+// ${ep.description}${tierComment}
 app.${ep.method.toLowerCase()}('${ep.path}',
   x402Middleware({
     amount: '${amountSmallest}',
-    address: env.RECIPIENT_ADDRESS,
-    network: env.NETWORK as 'mainnet' | 'testnet',
     tokenType: '${ep.tokenType}',
-    facilitatorUrl: env.FACILITATOR_URL,
   }),
   async (c) => {
-    const payment = c.get('payment');
+    const payment = c.get('x402');
 ${exampleLogic}
   }
 );`;
@@ -62,9 +80,8 @@ function generateExampleLogic(ep) {
       success: true,
       data: result,
       payment: {
-        txId: payment?.txId,
-        sender: payment?.sender,
-        amount: payment?.amount?.toString(),
+        txId: payment?.settleResult?.txId,
+        sender: payment?.payerAddress,
       },
     });`;
     }
@@ -81,9 +98,8 @@ function generateExampleLogic(ep) {
       success: true,
       data,
       payment: {
-        txId: payment?.txId,
-        sender: payment?.sender,
-        amount: payment?.amount?.toString(),
+        txId: payment?.settleResult?.txId,
+        sender: payment?.payerAddress,
       },
     });`;
 }
@@ -93,9 +109,11 @@ function generateExampleLogic(ep) {
 function generateEndpointDocs(endpoints) {
     return endpoints
         .map((ep) => {
+        const amount = getEndpointAmount(ep);
+        const tierInfo = ep.tier ? ` (tier: ${ep.tier})` : "";
         return `### ${ep.method} ${ep.path}
 - **Description:** ${ep.description}
-- **Cost:** ${ep.amount} ${ep.tokenType}
+- **Cost:** ${amount} ${ep.tokenType}${tierInfo}
 - **Payment Required:** Yes`;
     })
         .join("\n\n");
@@ -112,247 +130,382 @@ function generateTokenList(endpoints) {
 // =============================================================================
 function getIndexTemplate(endpoints) {
     const endpointCode = generateEndpointCode(endpoints);
-    return `import { Hono } from 'hono';
+    return `// BigInt.toJSON polyfill for JSON.stringify compatibility
+(BigInt.prototype as unknown as { toJSON: () => string }).toJSON = function () {
+  return this.toString();
+};
+
+import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { x402Middleware } from './x402-middleware';
+import type { X402Context } from './x402-middleware';
 
-type Bindings = {
+type Env = {
   RECIPIENT_ADDRESS: string;
   NETWORK: string;
   FACILITATOR_URL: string;
 };
 
 type Variables = {
-  payment?: {
-    txId: string;
-    status: string;
-    sender: string;
-    recipient: string;
-    amount: bigint;
-  };
+  x402?: X402Context;
 };
 
-const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+const app = new Hono<{ Bindings: Env; Variables: Variables }>();
 
-app.use('*', cors());
+// CORS middleware with x402 headers
+app.use('*', cors({
+  origin: '*',
+  allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+  allowHeaders: ['X-PAYMENT', 'X-PAYMENT-TOKEN-TYPE', 'Authorization', 'Content-Type'],
+  exposeHeaders: ['X-PAYMENT-RESPONSE', 'X-PAYER-ADDRESS'],
+}));
 
 // Startup validation - fail fast if required secrets are missing
 app.use('*', async (c, next) => {
+  // Skip validation for health check
+  if (c.req.path === '/health') {
+    return next();
+  }
+
   const missingSecrets: string[] = [];
 
   if (!c.env.RECIPIENT_ADDRESS) {
     missingSecrets.push('RECIPIENT_ADDRESS');
   }
-  if (!c.env.FACILITATOR_URL) {
-    missingSecrets.push('FACILITATOR_URL');
-  }
 
   if (missingSecrets.length > 0) {
     return c.json({
       error: 'Server configuration error',
       message: \`Missing required secrets: \${missingSecrets.join(', ')}\`,
-      hint: missingSecrets.map(s => \`Run: npm run wrangler -- secret put \${s}\`).join(' && '),
+      hint: missingSecrets.map(s => \`Run: wrangler secret put \${s}\`).join(' && '),
     }, 503);
   }
 
   await next();
 });
 
+// Service info at root (free)
+app.get('/', (c) => {
+  return c.json({
+    service: '${endpoints.length > 0 ? "x402-api" : "my-x402-api"}',
+    version: '1.0.0',
+    health: '/health',
+    payment: {
+      tokens: ['STX', 'sBTC', 'USDCx'],
+      header: 'X-PAYMENT',
+      tokenTypeHeader: 'X-PAYMENT-TOKEN-TYPE',
+    },
+  });
+});
+
 // Health check (free)
 app.get('/health', (c) => {
   return c.json({
     status: 'ok',
     timestamp: new Date().toISOString(),
+    network: c.env.NETWORK || 'testnet',
   });
 });
-
-// x402-protected endpoints
-app.use('*', async (c, next) => {
-  // Make env available to middleware
-  const env = c.env;
-  (globalThis as Record<string, unknown>).__env = env;
-  await next();
-});
-
-const env = {
-  get RECIPIENT_ADDRESS() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.RECIPIENT_ADDRESS || '';
-  },
-  get NETWORK() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.NETWORK || 'testnet';
-  },
-  get FACILITATOR_URL() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.FACILITATOR_URL || '';
-  },
-};
 ${endpointCode}
 
 export default app;
 `;
 }
 function getMiddlewareTemplate() {
-    return `import type { Context, Next } from 'hono';
+    return `/**
+ * x402 Payment Middleware for Hono
+ *
+ * Based on production implementations from:
+ * - https://github.com/aibtcdev/x402-api
+ * - https://github.com/whoabuddy/stx402
+ *
+ * Uses the x402-stacks library for payment verification.
+ */
+
+import type { Context, Next } from 'hono';
+import { X402PaymentVerifier } from 'x402-stacks';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type TokenType = 'STX' | 'sBTC' | 'USDCx';
+
+export interface TokenContract {
+  address: string;
+  name: string;
+}
 
 export interface X402Config {
   amount: string;
-  address: string;
-  network: 'mainnet' | 'testnet';
-  tokenType: 'STX' | 'sBTC' | 'USDCx';
-  facilitatorUrl?: string;
-  resource?: string;
+  tokenType: TokenType;
 }
 
-interface TokenContract {
-  address: string;
-  name: string;
+export interface SettleResult {
+  isValid: boolean;
+  txId?: string;
+  status?: string;
+  sender?: string;
+  senderAddress?: string;
+  sender_address?: string;
+  recipient?: string;
+  error?: string;
+  reason?: string;
+  validationError?: string;
 }
 
-// Token contract addresses for payment verification
-const TOKEN_CONTRACTS: Record<string, Record<string, TokenContract | null>> = {
-  mainnet: {
-    STX: null,
-    sBTC: { address: 'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4', name: 'sbtc-token' },
-    USDCx: { address: 'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK', name: 'token-usdcx' },
-  },
-  testnet: {
-    STX: null,
-    sBTC: { address: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM', name: 'sbtc-token' },
-    USDCx: null,
-  },
-};
+export interface X402Context {
+  payerAddress: string;
+  settleResult: SettleResult;
+  signedTx: string;
+}
 
 interface PaymentRequirement {
   maxAmountRequired: string;
   resource: string;
   payTo: string;
-  network: string;
+  network: 'mainnet' | 'testnet';
   nonce: string;
   expiresAt: string;
-  tokenType: string;
+  tokenType: TokenType;
   tokenContract?: TokenContract;
 }
 
-interface SettleRequest {
-  signed_transaction: string;
-  expected_recipient: string;
-  min_amount: string;
-  network: string;
-  token_type: string;
+type PaymentErrorCode =
+  | 'FACILITATOR_UNAVAILABLE'
+  | 'FACILITATOR_ERROR'
+  | 'PAYMENT_INVALID'
+  | 'INSUFFICIENT_FUNDS'
+  | 'PAYMENT_EXPIRED'
+  | 'AMOUNT_TOO_LOW'
+  | 'NETWORK_ERROR'
+  | 'UNKNOWN_ERROR';
+
+interface PaymentErrorResponse {
+  error: string;
+  code: PaymentErrorCode;
+  retryAfter?: number;
+  tokenType: TokenType;
   resource: string;
-  method: string;
+  details?: Record<string, string | undefined>;
 }
 
-interface SettleResponse {
-  success: boolean;
-  tx_id?: string;
-  status?: string;
-  sender_address?: string;
-  recipient_address?: string;
-  amount?: number;
-  error?: string;
+// =============================================================================
+// Token Contracts (correct mainnet/testnet addresses)
+// =============================================================================
+
+const TOKEN_CONTRACTS: Record<'mainnet' | 'testnet', Record<'sBTC' | 'USDCx', TokenContract>> = {
+  mainnet: {
+    sBTC: { address: 'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4', name: 'sbtc-token' },
+    USDCx: { address: 'SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE', name: 'usdcx' },
+  },
+  testnet: {
+    sBTC: { address: 'ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT', name: 'sbtc-token' },
+    USDCx: { address: 'ST1NXBK3K5YYMD6FD41MVNP3JS1GABZ8TRVX023PT', name: 'usdcx' },
+  },
+};
+
+// =============================================================================
+// Error Classification
+// =============================================================================
+
+function classifyPaymentError(error: unknown, settleResult?: SettleResult): {
+  code: PaymentErrorCode;
+  message: string;
+  httpStatus: number;
+  retryAfter?: number;
+} {
+  const errorStr = String(error).toLowerCase();
+  const resultError = settleResult?.error?.toLowerCase() || '';
+  const resultReason = settleResult?.reason?.toLowerCase() || '';
+  const validationError = settleResult?.validationError?.toLowerCase() || '';
+  const combined = \`\${errorStr} \${resultError} \${resultReason} \${validationError}\`;
+
+  if (combined.includes('fetch') || combined.includes('network') || combined.includes('timeout')) {
+    return { code: 'NETWORK_ERROR', message: 'Network error with payment facilitator', httpStatus: 502, retryAfter: 5 };
+  }
+
+  if (combined.includes('503') || combined.includes('unavailable')) {
+    return { code: 'FACILITATOR_UNAVAILABLE', message: 'Payment facilitator temporarily unavailable', httpStatus: 503, retryAfter: 30 };
+  }
+
+  if (combined.includes('insufficient') || combined.includes('balance')) {
+    return { code: 'INSUFFICIENT_FUNDS', message: 'Insufficient funds in wallet', httpStatus: 402 };
+  }
+
+  if (combined.includes('expired') || combined.includes('nonce')) {
+    return { code: 'PAYMENT_EXPIRED', message: 'Payment expired, please sign a new payment', httpStatus: 402 };
+  }
+
+  if (combined.includes('amount') && (combined.includes('low') || combined.includes('minimum'))) {
+    return { code: 'AMOUNT_TOO_LOW', message: 'Payment amount below minimum required', httpStatus: 402 };
+  }
+
+  if (combined.includes('invalid') || combined.includes('signature')) {
+    return { code: 'PAYMENT_INVALID', message: 'Invalid payment signature', httpStatus: 400 };
+  }
+
+  return { code: 'UNKNOWN_ERROR', message: 'Payment processing error', httpStatus: 500, retryAfter: 5 };
 }
 
+// =============================================================================
+// Middleware
+// =============================================================================
+
+type Env = {
+  RECIPIENT_ADDRESS: string;
+  NETWORK: string;
+  FACILITATOR_URL: string;
+};
+
 /**
- * x402 Payment Middleware for Hono
+ * x402 Payment Middleware
  *
  * Handles the x402 payment flow:
  * 1. If no X-PAYMENT header, return 402 with payment requirements
  * 2. If X-PAYMENT header present, verify payment via facilitator
- * 3. On success, attach payment info and continue to handler
+ * 3. On success, attach payment context and continue to handler
  */
 export function x402Middleware(config: X402Config) {
-  const facilitatorUrl = config.facilitatorUrl || 'https://facilitator.x402stacks.xyz';
-  const tokenContract = TOKEN_CONTRACTS[config.network]?.[config.tokenType] || null;
-
-  return async (c: Context, next: Next) => {
-    const signedPayment = c.req.header('x-payment');
+  return async (c: Context<{ Bindings: Env; Variables: { x402?: X402Context } }>, next: Next) => {
+    const env = c.env;
+    const network = (env.NETWORK || 'testnet') as 'mainnet' | 'testnet';
+    const facilitatorUrl = env.FACILITATOR_URL || 'https://facilitator.x402stacks.xyz';
+    const recipientAddress = env.RECIPIENT_ADDRESS;
+
+    // Get token type from header or use config default
+    const headerTokenType = c.req.header('X-PAYMENT-TOKEN-TYPE');
+    const tokenType = (headerTokenType?.toUpperCase() === 'SBTC' ? 'sBTC' :
+                       headerTokenType?.toUpperCase() === 'USDCX' ? 'USDCx' :
+                       headerTokenType?.toUpperCase() === 'STX' ? 'STX' :
+                       config.tokenType) as TokenType;
+
+    const minAmount = BigInt(config.amount);
+    const signedTx = c.req.header('X-PAYMENT');
+
+    if (!signedTx) {
+      // Return 402 Payment Required
+      let tokenContract: TokenContract | undefined;
+      if (tokenType === 'sBTC' || tokenType === 'USDCx') {
+        tokenContract = TOKEN_CONTRACTS[network][tokenType];
+      }
 
-    if (!signedPayment) {
-      // Return 402 Payment Required with payment details
       const paymentReq: PaymentRequirement = {
         maxAmountRequired: config.amount,
-        resource: config.resource || c.req.path,
-        payTo: config.address,
-        network: config.network,
+        resource: c.req.path,
+        payTo: recipientAddress,
+        network,
         nonce: crypto.randomUUID(),
-        expiresAt: new Date(Date.now() + 300000).toISOString(),
-        tokenType: config.tokenType,
+        expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+        tokenType,
+        ...(tokenContract && { tokenContract }),
       };
 
-      if (tokenContract) {
-        paymentReq.tokenContract = tokenContract;
-      }
-
       return c.json(paymentReq, 402);
     }
 
-    // Verify and settle payment via facilitator
+    // Verify payment via x402-stacks
+    const verifier = new X402PaymentVerifier(facilitatorUrl, network);
+
+    let settleResult: SettleResult;
     try {
-      const settleRequest: SettleRequest = {
-        signed_transaction: signedPayment,
-        expected_recipient: config.address,
-        min_amount: config.amount,
-        network: config.network,
-        token_type: config.tokenType.toUpperCase(),
-        resource: config.resource || c.req.path,
-        method: c.req.method,
+      settleResult = await verifier.settlePayment(signedTx, {
+        expectedRecipient: recipientAddress,
+        minAmount,
+        tokenType,
+      }) as SettleResult;
+    } catch (error) {
+      const classified = classifyPaymentError(error);
+
+      const errorResponse: PaymentErrorResponse = {
+        error: classified.message,
+        code: classified.code,
+        retryAfter: classified.retryAfter,
+        tokenType,
+        resource: c.req.path,
+        details: { exceptionMessage: String(error) },
       };
 
-      const response = await fetch(\`\${facilitatorUrl}/api/v1/settle\`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(settleRequest),
-      });
-
-      const result = (await response.json()) as SettleResponse;
-
-      if (!result.success) {
-        return c.json(
-          {
-            error: 'Payment verification failed',
-            reason: result.error || 'Unknown error',
-          },
-          402
-        );
+      if (classified.retryAfter) {
+        c.header('Retry-After', String(classified.retryAfter));
       }
 
-      // Store payment info in context for handler to use
-      c.set('payment', {
-        txId: result.tx_id,
-        status: result.status,
-        sender: result.sender_address,
-        recipient: result.recipient_address,
-        amount: BigInt(result.amount || 0),
-      });
+      return c.json(errorResponse, classified.httpStatus as 400 | 402 | 500 | 502 | 503);
+    }
 
-      await next();
-    } catch (error) {
-      return c.json(
-        {
-          error: 'Payment processing error',
-          message: error instanceof Error ? error.message : 'Unknown error',
-        },
-        500
+    if (!settleResult.isValid) {
+      const classified = classifyPaymentError(
+        settleResult.validationError || settleResult.error || 'invalid',
+        settleResult
       );
+
+      const errorResponse: PaymentErrorResponse = {
+        error: classified.message,
+        code: classified.code,
+        retryAfter: classified.retryAfter,
+        tokenType,
+        resource: c.req.path,
+        details: {
+          settleError: settleResult.error,
+          settleReason: settleResult.reason,
+          validationError: settleResult.validationError,
+        },
+      };
+
+      if (classified.retryAfter) {
+        c.header('Retry-After', String(classified.retryAfter));
+      }
+
+      return c.json(errorResponse, classified.httpStatus as 400 | 402 | 500 | 502 | 503);
     }
+
+    // Extract payer address
+    const payerAddress = settleResult.senderAddress || settleResult.sender_address || settleResult.sender || 'unknown';
+
+    // Store context for downstream handlers
+    c.set('x402', {
+      payerAddress,
+      settleResult,
+      signedTx,
+    });
+
+    // Add response headers
+    c.header('X-PAYMENT-RESPONSE', JSON.stringify(settleResult));
+    c.header('X-PAYER-ADDRESS', payerAddress);
+
+    await next();
   };
 }
 `;
 }
 function getWranglerTemplate(projectName, network, facilitatorUrl) {
+    const mainnetFacilitator = "https://facilitator.x402stacks.xyz";
     return `{
+  "$schema": "node_modules/wrangler/config-schema.json",
   "name": "${projectName}",
   "main": "src/index.ts",
   "compatibility_date": "2026-01-14",
-  "compatibility_flags": ["nodejs_compat"],
+  "compatibility_flags": ["nodejs_compat_v2"],
+  "workers_dev": true,
   "vars": {
     "NETWORK": "${network}",
     "FACILITATOR_URL": "${facilitatorUrl}"
   },
   "env": {
+    "staging": {
+      "name": "${projectName}-staging",
+      "workers_dev": true,
+      "vars": {
+        "NETWORK": "testnet",
+        "FACILITATOR_URL": "${facilitatorUrl}"
+      }
+    },
     "production": {
+      "name": "${projectName}",
+      "workers_dev": false,
       "vars": {
-        "NETWORK": "mainnet"
+        "NETWORK": "mainnet",
+        "FACILITATOR_URL": "${mainnetFacilitator}"
       }
     }
   }
@@ -366,20 +519,21 @@ function getPackageJsonTemplate(projectName) {
   "private": true,
   "type": "module",
   "scripts": {
-    "wrangler": "set -a && . ./.env && set +a && wrangler",
-    "dev": "npm run wrangler -- dev",
-    "deploy": "npm run wrangler -- deploy",
-    "deploy:dry": "npm run wrangler -- deploy --dry-run",
-    "deploy:production": "npm run wrangler -- deploy --env production",
-    "tail": "npm run wrangler -- tail"
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:production": "wrangler deploy --env production",
+    "tail": "wrangler tail",
+    "cf-typegen": "wrangler types"
   },
   "dependencies": {
-    "hono": "^4.7.0"
+    "hono": "^4.7.0",
+    "x402-stacks": "^1.1.1"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250109.0",
     "typescript": "^5.7.0",
-    "wrangler": "^4.5.0"
+    "wrangler": "^4.56.0"
   }
 }
 `;
@@ -405,13 +559,26 @@ function getTsconfigTemplate() {
 `;
 }
 function getEnvExampleTemplate(recipientAddress) {
-    return `# Cloudflare credentials
+    const addressNote = recipientAddress
+        ? `# Value: ${recipientAddress}`
+        : "# Value: Your Stacks address (SP... for mainnet, ST... for testnet)";
+    return `# Cloudflare credentials (only needed for CI/CD deployment)
+# For local dev, wrangler uses browser-based auth
 CLOUDFLARE_API_TOKEN=your-api-token-here
 CLOUDFLARE_ACCOUNT_ID=your-account-id-here
 
 # x402 recipient address (set via wrangler secret)
 # wrangler secret put RECIPIENT_ADDRESS
-# Value: ${recipientAddress}
+${addressNote}
+`;
+}
+function getDevVarsTemplate(recipientAddress) {
+    const address = recipientAddress || "YOUR_STACKS_ADDRESS_HERE";
+    return `# Local development variables
+# These are used by wrangler dev and are NOT deployed to production
+# For production secrets, use: wrangler secret put RECIPIENT_ADDRESS
+
+RECIPIENT_ADDRESS=${address}
 `;
 }
 function getGitignoreTemplate() {
@@ -425,66 +592,64 @@ dist/
 function getReadmeTemplate(projectName, endpoints, recipientAddress) {
     const tokenList = generateTokenList(endpoints);
     const endpointDocs = generateEndpointDocs(endpoints);
+    const addressDisplay = recipientAddress || "YOUR_STACKS_ADDRESS";
     return `# ${projectName}
 
 x402-enabled API endpoints on Cloudflare Workers.
 
+Built using patterns from:
+- [x402-api](https://github.com/aibtcdev/x402-api)
+- [stx402](https://github.com/whoabuddy/stx402)
+
+## Quick Start
+
+\`\`\`bash
+# Install dependencies
+npm install
+
+# Set your recipient address for local dev
+# Edit .dev.vars and replace YOUR_STACKS_ADDRESS_HERE with your address
+
+# Start local dev server
+npm run dev
+\`\`\`
+
+The server will start at http://localhost:8787
+
 ## Payment Tokens
 
 This API accepts payments in:
 ${tokenList}
 
-## Recipient Address
-
-Payments are sent to: \`${recipientAddress}\`
-
 ## Endpoints
 
+### GET /
+- **Description:** Service info
+- **Cost:** Free
+
 ### GET /health
 - **Description:** Health check endpoint
 - **Cost:** Free
-- **Payment Required:** No
 
 ${endpointDocs}
 
-## Setup
-
-1. Install dependencies:
-   \`\`\`bash
-   npm install
-   \`\`\`
-
-2. Create \`.env\` file from \`.env.example\`:
-   \`\`\`bash
-   cp .env.example .env
-   \`\`\`
+## Deployment
 
-3. Add your Cloudflare credentials to \`.env\`
-
-4. Set the recipient address as a secret:
-   \`\`\`bash
-   npm run wrangler -- secret put RECIPIENT_ADDRESS
-   # Enter: ${recipientAddress}
-   \`\`\`
-
-## Local Development
+### Set Production Secrets
 
 \`\`\`bash
-npm run dev
+# Set your recipient address (where payments will be sent)
+wrangler secret put RECIPIENT_ADDRESS
+# Enter: ${addressDisplay}
 \`\`\`
 
-The server will start at http://localhost:8787
-
-## Deploy
+### Deploy
 
 \`\`\`bash
-# Dry run first
-npm run deploy:dry
-
-# Deploy to staging
-npm run deploy
+# Deploy to staging (testnet)
+npm run deploy:staging
 
-# Deploy to production
+# Deploy to production (mainnet)
 npm run deploy:production
 \`\`\`
 
@@ -496,9 +661,11 @@ npm run deploy:production
    {
      "maxAmountRequired": "1000",
      "resource": "/api/endpoint",
-     "payTo": "${recipientAddress}",
+     "payTo": "${addressDisplay}",
      "network": "testnet",
-     "tokenType": "STX"
+     "tokenType": "STX",
+     "nonce": "uuid",
+     "expiresAt": "2024-01-01T00:05:00Z"
    }
    \`\`\`
 3. Client signs payment transaction (does NOT broadcast)
@@ -509,6 +676,9 @@ npm run deploy:production
 ## Testing with curl
 
 \`\`\`bash
+# Service info (free)
+curl http://localhost:8787/
+
 # Health check (free)
 curl http://localhost:8787/health
 
@@ -516,9 +686,33 @@ curl http://localhost:8787/health
 curl http://localhost:8787${endpoints[0]?.path || "/api/endpoint"}
 \`\`\`
 
+## Token Type Selection
+
+Clients can specify which token to pay with using the \`X-PAYMENT-TOKEN-TYPE\` header:
+
+\`\`\`bash
+# Pay with sBTC instead of STX
+curl -H "X-PAYMENT-TOKEN-TYPE: sBTC" http://localhost:8787${endpoints[0]?.path || "/api/endpoint"}
+\`\`\`
+
+Supported values: \`STX\`, \`sBTC\`, \`USDCx\`
+
+## Error Codes
+
+The API returns structured error responses for payment failures:
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| \`INSUFFICIENT_FUNDS\` | Wallet needs funding | 402 |
+| \`PAYMENT_EXPIRED\` | Sign a new payment | 402 |
+| \`AMOUNT_TOO_LOW\` | Payment below minimum | 402 |
+| \`PAYMENT_INVALID\` | Bad signature/params | 400 |
+| \`NETWORK_ERROR\` | Transient error | 502 |
+| \`FACILITATOR_UNAVAILABLE\` | Try again later | 503 |
+
 ---
 
-Generated with @aibtc/mcp-server scaffold tool.
+Generated with [@aibtc/mcp-server](https://www.npmjs.com/package/@aibtc/mcp-server) scaffold tool.
 `;
 }
 // =============================================================================
@@ -553,6 +747,7 @@ export async function scaffoldProject(config) {
         { name: "package.json", content: getPackageJsonTemplate(projectName) },
         { name: "tsconfig.json", content: getTsconfigTemplate() },
         { name: ".env.example", content: getEnvExampleTemplate(recipientAddress) },
+        { name: ".dev.vars", content: getDevVarsTemplate(recipientAddress) },
         { name: ".gitignore", content: getGitignoreTemplate() },
         { name: "README.md", content: getReadmeTemplate(projectName, endpoints, recipientAddress) },
     ];
@@ -561,16 +756,22 @@ export async function scaffoldProject(config) {
         await fs.writeFile(filePath, file.content, "utf-8");
         filesCreated.push(file.name);
     }
+    const addressInstruction = recipientAddress
+        ? `wrangler secret put RECIPIENT_ADDRESS (enter: ${recipientAddress})`
+        : "wrangler secret put RECIPIENT_ADDRESS (enter your Stacks address)";
     return {
         projectPath,
         filesCreated,
         nextSteps: [
             `cd ${projectPath}`,
             "npm install",
-            "cp .env.example .env",
-            "# Add your Cloudflare credentials to .env",
-            `npm run wrangler -- secret put RECIPIENT_ADDRESS (enter: ${recipientAddress})`,
+            recipientAddress
+                ? "# .dev.vars is pre-configured with your address"
+                : "# Edit .dev.vars and set your RECIPIENT_ADDRESS",
             "npm run dev",
+            "# For production deployment:",
+            addressInstruction,
+            "npm run deploy:production",
         ],
     };
 }
@@ -611,13 +812,10 @@ function generateAIEndpointCode(endpoints, defaultModel) {
 app.post('${ep.path}',
   x402Middleware({
     amount: '${amountSmallest}',
-    address: env.RECIPIENT_ADDRESS,
-    network: env.NETWORK as 'mainnet' | 'testnet',
     tokenType: '${ep.tokenType}',
-    facilitatorUrl: env.FACILITATOR_URL,
   }),
   async (c) => {
-    const payment = c.get('payment');
+    const payment = c.get('x402');
     const body = await c.req.json<{ prompt?: string; message?: string; text?: string; targetLanguage?: string }>();
     const userInput = body.prompt || body.message || body.text || '';
 
@@ -626,7 +824,7 @@ app.post('${ep.path}',
     }
 
     const result = await callOpenRouter({
-      apiKey: env.OPENROUTER_API_KEY,
+      apiKey: c.env.OPENROUTER_API_KEY,
       model: '${model}',
       systemPrompt: \`${systemPrompt.replace(/`/g, "\\`")}\`,
       userMessage: ${ep.aiType === "translate" ? "`Translate to ${body.targetLanguage || 'English'}: ${userInput}`" : "userInput"},
@@ -636,7 +834,10 @@ app.post('${ep.path}',
       result: result.content,
       model: result.model,
       usage: result.usage,
-      txId: payment?.txId,
+      payment: {
+        txId: payment?.settleResult?.txId,
+        sender: payment?.payerAddress,
+      },
     });
   }
 );`;
@@ -658,12 +859,18 @@ function generateAIEndpointDocs(endpoints) {
 }
 function getAIIndexTemplate(endpoints, defaultModel) {
     const endpointCode = generateAIEndpointCode(endpoints, defaultModel);
-    return `import { Hono } from 'hono';
+    return `// BigInt.toJSON polyfill for JSON.stringify compatibility
+(BigInt.prototype as unknown as { toJSON: () => string }).toJSON = function () {
+  return this.toString();
+};
+
+import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { x402Middleware } from './x402-middleware';
+import type { X402Context } from './x402-middleware';
 import { callOpenRouter } from './openrouter';
 
-type Bindings = {
+type Env = {
   RECIPIENT_ADDRESS: string;
   NETWORK: string;
   FACILITATOR_URL: string;
@@ -671,29 +878,31 @@ type Bindings = {
 };
 
 type Variables = {
-  payment?: {
-    txId: string;
-    status: string;
-    sender: string;
-    recipient: string;
-    amount: bigint;
-  };
+  x402?: X402Context;
 };
 
-const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+const app = new Hono<{ Bindings: Env; Variables: Variables }>();
 
-app.use('*', cors());
+// CORS middleware with x402 headers
+app.use('*', cors({
+  origin: '*',
+  allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+  allowHeaders: ['X-PAYMENT', 'X-PAYMENT-TOKEN-TYPE', 'Authorization', 'Content-Type'],
+  exposeHeaders: ['X-PAYMENT-RESPONSE', 'X-PAYER-ADDRESS'],
+}));
 
 // Startup validation - fail fast if required secrets are missing
 app.use('*', async (c, next) => {
+  // Skip validation for health check and root
+  if (c.req.path === '/health' || c.req.path === '/') {
+    return next();
+  }
+
   const missingSecrets: string[] = [];
 
   if (!c.env.RECIPIENT_ADDRESS) {
     missingSecrets.push('RECIPIENT_ADDRESS');
   }
-  if (!c.env.FACILITATOR_URL) {
-    missingSecrets.push('FACILITATOR_URL');
-  }
   if (!c.env.OPENROUTER_API_KEY) {
     missingSecrets.push('OPENROUTER_API_KEY');
   }
@@ -702,43 +911,36 @@ app.use('*', async (c, next) => {
     return c.json({
       error: 'Server configuration error',
       message: \`Missing required secrets: \${missingSecrets.join(', ')}\`,
-      hint: missingSecrets.map(s => \`Run: npm run wrangler -- secret put \${s}\`).join(' && '),
+      hint: missingSecrets.map(s => \`Run: wrangler secret put \${s}\`).join(' && '),
     }, 503);
   }
 
   await next();
 });
 
+// Service info at root (free)
+app.get('/', (c) => {
+  return c.json({
+    service: 'x402-ai-api',
+    version: '1.0.0',
+    defaultModel: '${defaultModel}',
+    health: '/health',
+    payment: {
+      tokens: ['STX', 'sBTC', 'USDCx'],
+      header: 'X-PAYMENT',
+      tokenTypeHeader: 'X-PAYMENT-TOKEN-TYPE',
+    },
+  });
+});
+
 // Health check (free)
 app.get('/health', (c) => {
   return c.json({
     status: 'ok',
     timestamp: new Date().toISOString(),
+    network: c.env.NETWORK || 'testnet',
   });
 });
-
-// x402-protected AI endpoints
-app.use('*', async (c, next) => {
-  // Make env available to middleware
-  const env = c.env;
-  (globalThis as Record<string, unknown>).__env = env;
-  await next();
-});
-
-const env = {
-  get RECIPIENT_ADDRESS() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.RECIPIENT_ADDRESS || '';
-  },
-  get NETWORK() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.NETWORK || 'testnet';
-  },
-  get FACILITATOR_URL() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.FACILITATOR_URL || '';
-  },
-  get OPENROUTER_API_KEY() {
-    return ((globalThis as Record<string, unknown>).__env as Bindings)?.OPENROUTER_API_KEY || '';
-  },
-};
 ${endpointCode}
 
 export default app;
@@ -841,123 +1043,134 @@ function getAIPackageJsonTemplate(projectName) {
   "private": true,
   "type": "module",
   "scripts": {
-    "wrangler": "set -a && . ./.env && set +a && wrangler",
-    "dev": "npm run wrangler -- dev",
-    "deploy": "npm run wrangler -- deploy",
-    "deploy:dry": "npm run wrangler -- deploy --dry-run",
-    "deploy:production": "npm run wrangler -- deploy --env production",
-    "tail": "npm run wrangler -- tail"
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:production": "wrangler deploy --env production",
+    "tail": "wrangler tail",
+    "cf-typegen": "wrangler types"
   },
   "dependencies": {
-    "hono": "^4.7.0"
+    "hono": "^4.7.0",
+    "x402-stacks": "^1.1.1"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250109.0",
     "typescript": "^5.7.0",
-    "wrangler": "^4.5.0"
+    "wrangler": "^4.56.0"
   }
 }
 `;
 }
 function getAIEnvExampleTemplate(recipientAddress) {
-    return `# Cloudflare credentials
+    const addressNote = recipientAddress
+        ? `# Value: ${recipientAddress}`
+        : "# Value: Your Stacks address (SP... for mainnet, ST... for testnet)";
+    return `# Cloudflare credentials (only needed for CI/CD deployment)
+# For local dev, wrangler uses browser-based auth
 CLOUDFLARE_API_TOKEN=your-api-token-here
 CLOUDFLARE_ACCOUNT_ID=your-account-id-here
 
 # x402 recipient address (set via wrangler secret)
 # wrangler secret put RECIPIENT_ADDRESS
-# Value: ${recipientAddress}
+${addressNote}
 
 # OpenRouter API key (set via wrangler secret)
 # Get your key at https://openrouter.ai/keys
 # wrangler secret put OPENROUTER_API_KEY
 `;
 }
+function getAIDevVarsTemplate(recipientAddress) {
+    const address = recipientAddress || "YOUR_STACKS_ADDRESS_HERE";
+    return `# Local development variables
+# These are used by wrangler dev and are NOT deployed to production
+# For production secrets, use: wrangler secret put <SECRET_NAME>
+
+RECIPIENT_ADDRESS=${address}
+OPENROUTER_API_KEY=your-openrouter-key-here
+`;
+}
 function getAIReadmeTemplate(projectName, endpoints, recipientAddress, defaultModel) {
     const tokenList = [...new Set(endpoints.map((ep) => `- ${ep.tokenType}`))].join("\n");
     const endpointDocs = generateAIEndpointDocs(endpoints);
+    const addressDisplay = recipientAddress || "YOUR_STACKS_ADDRESS";
+    const modelDisplay = defaultModel || "anthropic/claude-3-haiku";
     return `# ${projectName}
 
 x402-enabled AI API endpoints on Cloudflare Workers, powered by OpenRouter.
 
+Built using patterns from:
+- [x402-api](https://github.com/aibtcdev/x402-api)
+- [stx402](https://github.com/whoabuddy/stx402)
+
+## Quick Start
+
+\`\`\`bash
+# Install dependencies
+npm install
+
+# Edit .dev.vars with your settings:
+# - RECIPIENT_ADDRESS: Your Stacks address
+# - OPENROUTER_API_KEY: Get from https://openrouter.ai/keys
+
+# Start local dev server
+npm run dev
+\`\`\`
+
+The server will start at http://localhost:8787
+
 ## AI Provider
 
 This API uses [OpenRouter](https://openrouter.ai) to access AI models.
-Default model: \`${defaultModel}\`
+Default model: \`${modelDisplay}\`
 
 ## Payment Tokens
 
 This API accepts payments in:
 ${tokenList}
 
-## Recipient Address
-
-Payments are sent to: \`${recipientAddress}\`
-
 ## Endpoints
 
+### GET /
+- **Description:** Service info
+- **Cost:** Free
+
 ### GET /health
 - **Description:** Health check endpoint
 - **Cost:** Free
-- **Payment Required:** No
 
 ${endpointDocs}
 
-## Setup
-
-1. Install dependencies:
-   \`\`\`bash
-   npm install
-   \`\`\`
-
-2. Create \`.env\` file from \`.env.example\`:
-   \`\`\`bash
-   cp .env.example .env
-   \`\`\`
-
-3. Add your Cloudflare credentials to \`.env\`
-
-4. Set secrets:
-   \`\`\`bash
-   # Recipient address for payments
-   npm run wrangler -- secret put RECIPIENT_ADDRESS
-   # Enter: ${recipientAddress}
+## Deployment
 
-   # OpenRouter API key (get from https://openrouter.ai/keys)
-   npm run wrangler -- secret put OPENROUTER_API_KEY
-   \`\`\`
-
-## Local Development
+### Set Production Secrets
 
-For local development, create a \`.dev.vars\` file:
-\`\`\`
-RECIPIENT_ADDRESS=${recipientAddress}
-OPENROUTER_API_KEY=your-openrouter-key
-\`\`\`
-
-Then run:
 \`\`\`bash
-npm run dev
-\`\`\`
+# Set your recipient address (where payments will be sent)
+wrangler secret put RECIPIENT_ADDRESS
+# Enter: ${addressDisplay}
 
-The server will start at http://localhost:8787
+# Set your OpenRouter API key
+wrangler secret put OPENROUTER_API_KEY
+# Enter: your-api-key-from-openrouter.ai/keys
+\`\`\`
 
-## Deploy
+### Deploy
 
 \`\`\`bash
-# Dry run first
-npm run deploy:dry
+# Deploy to staging (testnet)
+npm run deploy:staging
 
-# Deploy to staging
-npm run deploy
-
-# Deploy to production
+# Deploy to production (mainnet)
 npm run deploy:production
 \`\`\`
 
 ## Example Usage
 
 \`\`\`bash
+# Service info (free)
+curl http://localhost:8787/
+
 # Health check (free)
 curl http://localhost:8787/health
 
@@ -976,21 +1189,46 @@ curl -X POST http://localhost:8787${endpoints[0]?.path || "/api/chat"} \\
 5. Server verifies and settles payment via facilitator
 6. Server calls OpenRouter API and returns AI response
 
+## Token Type Selection
+
+Clients can specify which token to pay with using the \`X-PAYMENT-TOKEN-TYPE\` header:
+
+\`\`\`bash
+# Pay with sBTC instead of STX
+curl -H "X-PAYMENT-TOKEN-TYPE: sBTC" -X POST http://localhost:8787${endpoints[0]?.path || "/api/chat"} \\
+  -H "Content-Type: application/json" \\
+  -d '{"prompt": "Hello"}'
+\`\`\`
+
+Supported values: \`STX\`, \`sBTC\`, \`USDCx\`
+
 ## OpenRouter Models
 
-You can use any model available on OpenRouter. Popular options:
-- \`anthropic/claude-3.5-sonnet\` - Best for complex tasks
-- \`anthropic/claude-3-haiku\` - Fast and affordable
+Popular options:
+- \`anthropic/claude-sonnet-4.5\` - Best overall, 1M context
+- \`anthropic/claude-3.5-haiku\` - Fast and affordable
 - \`openai/gpt-4o\` - OpenAI's latest
 - \`openai/gpt-4o-mini\` - Fast and cheap
-- \`meta-llama/llama-3.1-70b-instruct\` - Open source
-- \`google/gemini-pro-1.5\` - Google's model
+- \`google/gemini-2.5-flash\` - 1M context, fast
+- \`deepseek/deepseek-r1\` - Excellent reasoning
+- \`meta-llama/llama-3.3-70b-instruct\` - Best open source
 
 See all models: https://openrouter.ai/models
 
+## Error Codes
+
+| Code | Description | HTTP Status |
+|------|-------------|-------------|
+| \`INSUFFICIENT_FUNDS\` | Wallet needs funding | 402 |
+| \`PAYMENT_EXPIRED\` | Sign a new payment | 402 |
+| \`AMOUNT_TOO_LOW\` | Payment below minimum | 402 |
+| \`PAYMENT_INVALID\` | Bad signature/params | 400 |
+| \`NETWORK_ERROR\` | Transient error | 502 |
+| \`FACILITATOR_UNAVAILABLE\` | Try again later | 503 |
+
 ---
 
-Generated with @aibtc/mcp-server scaffold tool.
+Generated with [@aibtc/mcp-server](https://www.npmjs.com/package/@aibtc/mcp-server) scaffold tool.
 `;
 }
 // =============================================================================
@@ -1026,6 +1264,7 @@ export async function scaffoldAIProject(config) {
         { name: "package.json", content: getAIPackageJsonTemplate(projectName) },
         { name: "tsconfig.json", content: getTsconfigTemplate() },
         { name: ".env.example", content: getAIEnvExampleTemplate(recipientAddress) },
+        { name: ".dev.vars", content: getAIDevVarsTemplate(recipientAddress) },
         { name: ".gitignore", content: getGitignoreTemplate() },
         {
             name: "README.md",
@@ -1037,18 +1276,21 @@ export async function scaffoldAIProject(config) {
         await fs.writeFile(filePath, file.content, "utf-8");
         filesCreated.push(file.name);
     }
+    const addressInstruction = recipientAddress
+        ? `wrangler secret put RECIPIENT_ADDRESS (enter: ${recipientAddress})`
+        : "wrangler secret put RECIPIENT_ADDRESS (enter your Stacks address)";
     return {
         projectPath,
         filesCreated,
         nextSteps: [
             `cd ${projectPath}`,
             "npm install",
-            "cp .env.example .env",
-            "# Add your Cloudflare credentials to .env",
-            `npm run wrangler -- secret put RECIPIENT_ADDRESS (enter: ${recipientAddress})`,
-            "npm run wrangler -- secret put OPENROUTER_API_KEY (get from https://openrouter.ai/keys)",
-            "# For local dev, create .dev.vars with RECIPIENT_ADDRESS and OPENROUTER_API_KEY",
+            "# Edit .dev.vars with your RECIPIENT_ADDRESS and OPENROUTER_API_KEY",
             "npm run dev",
+            "# For production deployment:",
+            addressInstruction,
+            "wrangler secret put OPENROUTER_API_KEY (get from https://openrouter.ai/keys)",
+            "npm run deploy:production",
         ],
     };
 }