x402-engineer 0.1.0

package/skills/x402-stellar/references/patterns.md

@@ -0,0 +1,276 @@
+# x402-stellar Code Patterns
+
+These are **working, production-tested** patterns extracted from a deployed x402 POC. Use these exact patterns — do not improvise the import paths or class usage.
+
+## Server Pattern (Express + x402 Middleware)
+
+```typescript
+import express from "express";
+import { paymentMiddleware, x402ResourceServer } from "@x402/express";
+import { ExactStellarScheme } from "@x402/stellar/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import "dotenv/config";
+
+// 1. Create the facilitator client with auth headers
+const facilitatorClient = new HTTPFacilitatorClient({
+  url: process.env.FACILITATOR_URL || "https://channels.openzeppelin.com/x402/testnet",
+  createAuthHeaders: async () => {
+    const headers = { Authorization: `Bearer ${process.env.FACILITATOR_API_KEY}` };
+    return { verify: headers, settle: headers, supported: headers };
+  },
+});
+
+// 2. Create the resource server and register Stellar testnet
+const resourceServer = new x402ResourceServer(facilitatorClient).register(
+  "stellar:testnet",
+  new ExactStellarScheme()
+);
+
+// 3. Create Express app
+const app = express();
+app.use(express.json());
+
+// 4. Add payment middleware with route pricing
+app.use(
+  paymentMiddleware(
+    {
+      "POST /api/weather": {
+        accepts: [
+          {
+            scheme: "exact",
+            price: "$0.001",
+            network: "stellar:testnet",
+            payTo: process.env.SERVER_STELLAR_ADDRESS!,
+          },
+        ],
+        description: "Get weather data for a city",
+        mimeType: "application/json",
+      },
+    },
+    resourceServer
+  )
+);
+
+// 5. Define the actual route handler (runs only after payment verified)
+app.post("/api/weather", (req, res) => {
+  const { city } = req.body;
+  res.json({
+    city,
+    temperature: "22°C",
+    condition: "Sunny",
+    paid: true,
+  });
+});
+
+// 6. Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`x402 server running on port ${PORT}`);
+});
+```
+
+### Key Server Details
+
+- `ExactStellarScheme` on the server takes **no arguments** — it only verifies payments.
+- The `facilitatorClient` must return auth headers for `verify`, `settle`, and `supported`.
+- Route keys in the middleware config must match the HTTP method and path exactly: `"POST /api/weather"`.
+- The `price` field uses dollar-prefixed strings: `"$0.001"`, `"$0.01"`, `"$1.00"`.
+- The `payTo` address must be a valid Stellar public key (G...) with a USDC trustline.
+
+## Client Pattern (x402 Payment Client)
+
+```typescript
+import { createEd25519Signer } from "@x402/stellar";
+import { ExactStellarScheme } from "@x402/stellar/exact/client";
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import "dotenv/config";
+
+const SERVER_URL = process.env.SERVER_URL || "http://localhost:3000";
+
+// 1. Create the signer from the client's secret key
+const signer = createEd25519Signer(process.env.CLIENT_STELLAR_SECRET!);
+
+// 2. Create the scheme and register it with the x402 client
+const scheme = new ExactStellarScheme(signer);
+const client = new x402Client().register("stellar:testnet", scheme);
+const httpClient = new x402HTTPClient(client);
+
+async function callPaidEndpoint() {
+  // 3. Make the initial request (will get 402)
+  const initialResponse = await fetch(`${SERVER_URL}/api/weather`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ city: "Buenos Aires" }),
+  });
+
+  if (initialResponse.status !== 402) {
+    // Either succeeded without payment or got an error
+    console.log("Status:", initialResponse.status);
+    console.log("Body:", await initialResponse.text());
+    return;
+  }
+
+  // 4. Parse the 402 response to get payment requirements
+  const paymentRequired = httpClient.getPaymentRequiredResponse(
+    (name: string) => initialResponse.headers.get(name)
+  );
+
+  console.log("Payment required:", JSON.stringify(paymentRequired, null, 2));
+
+  // 5. Create the payment payload (signs the transaction)
+  const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
+
+  // 6. Encode the payment into headers
+  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+
+  // 7. Resend the request with payment headers
+  const paidResponse = await fetch(`${SERVER_URL}/api/weather`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...paymentHeaders,
+    },
+    body: JSON.stringify({ city: "Buenos Aires" }),
+  });
+
+  console.log("Paid response status:", paidResponse.status);
+  console.log("Paid response body:", await paidResponse.json());
+}
+
+callPaidEndpoint().catch(console.error);
+```
+
+### Key Client Details
+
+- `ExactStellarScheme` on the client takes the **signer** as an argument.
+- Import from `@x402/stellar/exact/client` — NOT from `@x402/stellar/exact/server`.
+- The `getPaymentRequiredResponse` method takes a header getter function.
+- The `encodePaymentSignatureHeader` returns an object that can be spread into fetch headers.
+- The client account must have USDC balance and a USDC trustline.
+
+## Multi-Endpoint Pricing Pattern
+
+```typescript
+app.use(
+  paymentMiddleware(
+    {
+      "POST /api/weather": {
+        accepts: [
+          {
+            scheme: "exact",
+            price: "$0.001",
+            network: "stellar:testnet",
+            payTo: process.env.SERVER_STELLAR_ADDRESS!,
+          },
+        ],
+        description: "Get weather data",
+        mimeType: "application/json",
+      },
+      "GET /api/premium-data": {
+        accepts: [
+          {
+            scheme: "exact",
+            price: "$0.01",
+            network: "stellar:testnet",
+            payTo: process.env.SERVER_STELLAR_ADDRESS!,
+          },
+        ],
+        description: "Access premium dataset",
+        mimeType: "application/json",
+      },
+      "POST /api/ai-summary": {
+        accepts: [
+          {
+            scheme: "exact",
+            price: "$0.05",
+            network: "stellar:testnet",
+            payTo: process.env.SERVER_STELLAR_ADDRESS!,
+          },
+        ],
+        description: "AI-generated summary",
+        mimeType: "application/json",
+      },
+    },
+    resourceServer
+  )
+);
+```
+
+Different endpoints can have different prices. Unprotected routes are not listed in the middleware config and work normally without payment.
+
+## Error Handling Patterns
+
+### Server-Side Error Handling
+
+```typescript
+// Wrap route handlers to catch errors after payment verification
+app.post("/api/weather", async (req, res) => {
+  try {
+    const { city } = req.body;
+    if (!city) {
+      return res.status(400).json({ error: "City parameter required" });
+    }
+    // Process and respond
+    res.json({ city, temperature: "22°C" });
+  } catch (error) {
+    console.error("Handler error:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+```
+
+### Client-Side Error Handling
+
+```typescript
+async function callWithRetry(url: string, options: RequestInit, maxRetries = 2) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+
+      if (response.status === 402) {
+        // Parse payment requirements and pay
+        const paymentRequired = httpClient.getPaymentRequiredResponse(
+          (name: string) => response.headers.get(name)
+        );
+        const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+
+        // Resend with payment
+        const paidResponse = await fetch(url, {
+          ...options,
+          headers: { ...options.headers, ...paymentHeaders },
+        });
+
+        if (!paidResponse.ok) {
+          throw new Error(`Payment accepted but request failed: ${paidResponse.status}`);
+        }
+        return paidResponse;
+      }
+
+      if (!response.ok) {
+        throw new Error(`Request failed: ${response.status}`);
+      }
+
+      return response;
+    } catch (error) {
+      if (attempt === maxRetries) throw error;
+      console.warn(`Attempt ${attempt + 1} failed, retrying...`);
+    }
+  }
+}
+```
+
+### Checking Payment Status
+
+```typescript
+// The payment middleware adds payment info to the request
+// Access it in your route handler if needed
+app.post("/api/weather", (req, res) => {
+  // The request only reaches here if payment was verified
+  // You can log payment details from the x-payment header
+  const paymentHeader = req.headers["x-payment"];
+  console.log("Payment received:", paymentHeader ? "yes" : "no");
+
+  res.json({ city: req.body.city, temperature: "22°C", paid: true });
+});
+```

package/skills/x402-stellar/references/setup.md

@@ -0,0 +1,138 @@
+# x402-stellar Setup Reference
+
+## 1. Create a Stellar Testnet Account
+
+Use the Stellar Laboratory to create and fund a testnet account.
+
+### Via Stellar Laboratory (recommended)
+
+1. Go to https://laboratory.stellar.org/#account-creator?network=test
+2. Click "Generate Keypair" — save both the **Public Key** (G...) and **Secret Key** (S...)
+3. Click "Fund account on testnet" to receive 10,000 test XLM from Friendbot
+
+### Via CLI
+
+```bash
+curl -s "https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY" | jq .
+```
+
+### Via Stellar SDK
+
+```typescript
+import { Keypair } from "@stellar/stellar-sdk";
+
+const keypair = Keypair.random();
+console.log("Public:", keypair.publicKey());   // G...
+console.log("Secret:", keypair.secret());      // S...
+
+// Fund on testnet
+await fetch(`https://friendbot.stellar.org?addr=${keypair.publicKey()}`);
+```
+
+You need **two accounts**:
+- **Server account** — receives USDC payments (use the Public Key as `SERVER_STELLAR_ADDRESS`)
+- **Client account** — signs and sends payments (use the Secret Key as `CLIENT_STELLAR_SECRET`)
+
+## 2. Get OpenZeppelin Facilitator API Key
+
+The facilitator verifies and settles x402 payments on behalf of your server.
+
+1. Go to https://channels.openzeppelin.com/testnet/gen
+2. Generate a new API key
+3. Save the key as `FACILITATOR_API_KEY` in your `.env`
+
+The facilitator URL for testnet is:
+```
+https://channels.openzeppelin.com/x402/testnet
+```
+
+For mainnet, use:
+```
+https://channels.openzeppelin.com/x402/mainnet
+```
+
+## 3. Environment Variable Reference
+
+| Variable | Format | Description | Where to Get It |
+|----------|--------|-------------|-----------------|
+| `SERVER_STELLAR_ADDRESS` | `G...` (56 chars) | Public key of the account receiving payments | Stellar Laboratory or SDK keypair generation |
+| `FACILITATOR_URL` | URL | OpenZeppelin facilitator endpoint | `https://channels.openzeppelin.com/x402/testnet` |
+| `FACILITATOR_API_KEY` | String | API key for the facilitator service | `channels.openzeppelin.com/testnet/gen` |
+| `CLIENT_STELLAR_SECRET` | `S...` (56 chars) | Secret key of the account making payments | Stellar Laboratory or SDK keypair generation |
+
+### Example `.env` file
+
+```env
+# Server configuration
+SERVER_STELLAR_ADDRESS=GBZXN7PIRZGNMHGA7MUUUF4GWZPWTQVL6NKRTZSKU74AQKLLP5LCBUS
+FACILITATOR_URL=https://channels.openzeppelin.com/x402/testnet
+FACILITATOR_API_KEY=oz_fac_abc123def456
+
+# Client configuration
+CLIENT_STELLAR_SECRET=SCZANGBA5YHTNYVVV3C7CAZMCLP4JMQ3HZRQMIV6ILWLHYZPXTLCWBI
+```
+
+## 4. Fund Testnet Account with USDC
+
+Testnet USDC is needed for the client account to make payments.
+
+### Step 1: Add USDC Trustline
+
+Before an account can hold USDC, it must establish a trustline to the USDC issuer.
+
+**Testnet USDC issuer:** `GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`
+
+```typescript
+import {
+  Keypair,
+  Server,
+  TransactionBuilder,
+  Networks,
+  Operation,
+  Asset,
+} from "@stellar/stellar-sdk";
+
+const server = new Server("https://horizon-testnet.stellar.org");
+const keypair = Keypair.fromSecret(process.env.CLIENT_STELLAR_SECRET!);
+const account = await server.loadAccount(keypair.publicKey());
+
+const usdcAsset = new Asset(
+  "USDC",
+  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
+);
+
+const tx = new TransactionBuilder(account, {
+  fee: "100",
+  networkPassphrase: Networks.TESTNET,
+})
+  .addOperation(Operation.changeTrust({ asset: usdcAsset }))
+  .setTimeout(30)
+  .build();
+
+tx.sign(keypair);
+await server.submitTransaction(tx);
+console.log("USDC trustline added");
+```
+
+### Step 2: Get Testnet USDC
+
+Use the testnet USDC faucet or transfer from a funded testnet account. Check the Stellar Laboratory for testnet USDC distribution tools.
+
+You can also use the Stellar Laboratory to manually add a trustline:
+1. Go to https://laboratory.stellar.org/#txbuilder?network=test
+2. Set source account to your client public key
+3. Add a "Change Trust" operation with USDC asset and the testnet issuer
+4. Sign and submit
+
+## 5. Verify Setup
+
+Run the dependency checker script to validate everything is configured:
+
+```bash
+node scripts/check-deps.js
+```
+
+This checks:
+- All @x402 packages are installed
+- All required environment variables are set
+- Variable formats are correct (G... for public keys, S... for secrets)

package/skills/x402-stellar/scripts/check-deps.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+/**
+ * x402-stellar dependency and environment checker
+ *
+ * Checks that all required @x402 packages are installed and
+ * that environment variables are properly configured.
+ *
+ * Usage: node scripts/check-deps.js
+ * Exit codes: 0 = all checks passed, 1 = one or more checks failed
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const REQUIRED_PACKAGES = [
+  "@x402/express",
+  "@x402/stellar",
+  "@x402/core",
+  "@stellar/stellar-sdk",
+];
+
+const REQUIRED_ENV_VARS = [
+  {
+    name: "SERVER_STELLAR_ADDRESS",
+    description: "Stellar public key for receiving payments",
+    validate: (val) => /^G[A-Z0-9]{55}$/.test(val),
+    hint: "Must be a Stellar public key starting with G (56 characters)",
+  },
+  {
+    name: "FACILITATOR_URL",
+    description: "OpenZeppelin facilitator endpoint URL",
+    validate: (val) => val.startsWith("https://"),
+    hint: "Use https://channels.openzeppelin.com/x402/testnet for testnet",
+  },
+  {
+    name: "FACILITATOR_API_KEY",
+    description: "API key for the facilitator service",
+    validate: (val) => val.length > 0,
+    hint: "Generate at channels.openzeppelin.com/testnet/gen",
+  },
+  {
+    name: "CLIENT_STELLAR_SECRET",
+    description: "Stellar secret key for signing payments",
+    validate: (val) => /^S[A-Z0-9]{55}$/.test(val),
+    hint: "Must be a Stellar secret key starting with S (56 characters)",
+  },
+];
+
+function checkPackages() {
+  const checks = [];
+  let packageJson;
+
+  // Find package.json by walking up from cwd
+  let dir = process.cwd();
+  let packageJsonPath = null;
+
+  while (dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, "package.json");
+    if (fs.existsSync(candidate)) {
+      packageJsonPath = candidate;
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+
+  if (!packageJsonPath) {
+    checks.push({
+      type: "package",
+      name: "package.json",
+      status: "error",
+      message: "No package.json found in current directory or parent directories",
+    });
+    return checks;
+  }
+
+  try {
+    packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (err) {
+    checks.push({
+      type: "package",
+      name: "package.json",
+      status: "error",
+      message: `Failed to parse package.json: ${err.message}`,
+    });
+    return checks;
+  }
+
+  const allDeps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  };
+
+  for (const pkg of REQUIRED_PACKAGES) {
+    if (allDeps && allDeps[pkg]) {
+      checks.push({
+        type: "package",
+        name: pkg,
+        status: "ok",
+        message: `Installed (${allDeps[pkg]})`,
+      });
+    } else {
+      checks.push({
+        type: "package",
+        name: pkg,
+        status: "error",
+        message: `Not found in package.json. Run: npm install ${pkg}`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function checkEnvVars() {
+  const checks = [];
+
+  // Try to load .env file
+  const envPath = path.join(process.cwd(), ".env");
+  const envVars = { ...process.env };
+
+  if (fs.existsSync(envPath)) {
+    try {
+      const envContent = fs.readFileSync(envPath, "utf8");
+      const lines = envContent.split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1) continue;
+        const key = trimmed.substring(0, eqIndex).trim();
+        let value = trimmed.substring(eqIndex + 1).trim();
+        // Remove surrounding quotes
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
+          value = value.slice(1, -1);
+        }
+        envVars[key] = value;
+      }
+    } catch (err) {
+      checks.push({
+        type: "env",
+        name: ".env",
+        status: "error",
+        message: `Failed to read .env file: ${err.message}`,
+      });
+    }
+  } else {
+    checks.push({
+      type: "env",
+      name: ".env",
+      status: "warning",
+      message: "No .env file found. Environment variables must be set in the shell.",
+    });
+  }
+
+  for (const envVar of REQUIRED_ENV_VARS) {
+    const value = envVars[envVar.name];
+    if (!value) {
+      checks.push({
+        type: "env",
+        name: envVar.name,
+        status: "error",
+        message: `Not set. ${envVar.description}. ${envVar.hint}`,
+      });
+    } else if (!envVar.validate(value)) {
+      checks.push({
+        type: "env",
+        name: envVar.name,
+        status: "error",
+        message: `Invalid format. ${envVar.hint}`,
+      });
+    } else {
+      const masked = value.substring(0, 4) + "..." + value.substring(value.length - 4);
+      checks.push({
+        type: "env",
+        name: envVar.name,
+        status: "ok",
+        message: `Set (${masked})`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function main() {
+  const packageChecks = checkPackages();
+  const envChecks = checkEnvVars();
+  const allChecks = [...packageChecks, ...envChecks];
+
+  const hasErrors = allChecks.some((c) => c.status === "error");
+  const result = {
+    status: hasErrors ? "error" : "ok",
+    checks: allChecks,
+  };
+
+  // Pretty print to stderr for humans
+  console.error("\nx402-stellar Dependency Check");
+  console.error("=".repeat(40));
+
+  for (const check of allChecks) {
+    const icon = check.status === "ok" ? "[OK]" : check.status === "warning" ? "[WARN]" : "[ERR]";
+    console.error(`${icon} ${check.name}: ${check.message}`);
+  }
+
+  console.error("=".repeat(40));
+  console.error(hasErrors ? "Some checks failed.\n" : "All checks passed.\n");
+
+  // JSON to stdout for programmatic use
+  console.log(JSON.stringify(result, null, 2));
+
+  process.exit(hasErrors ? 1 : 0);
+}
+
+main();