x402-engineer 0.1.0

package/skills/x402-debug/references/checklist.md

@@ -0,0 +1,146 @@
+# x402 Debug Checklist
+
+Comprehensive diagnostic checklist for `/x402:debug`. Run every check in order. Report results using `[PASS]`, `[FAIL]`, or `[WARN]` prefixes.
+
+## Category 1: Environment Variables
+
+### Check: SERVER_STELLAR_ADDRESS
+- **How:** Read `.env.local` (or `.env`) and check for `SERVER_STELLAR_ADDRESS`
+- **PASS:** Variable is set, value starts with `G`, length is 56 characters
+  - Output: `[PASS] SERVER_STELLAR_ADDRESS`
+- **FAIL:** Variable not set or empty
+  - Output: `[FAIL] Environment variable SERVER_STELLAR_ADDRESS: Not set`
+  - Fix: `Add SERVER_STELLAR_ADDRESS to .env.local (see .env.example)`
+- **WARN:** Variable is set but doesn't start with `G` or length is not 56
+  - Output: `[WARN] SERVER_STELLAR_ADDRESS: Value doesn't look like a Stellar public key (expected G... with 56 chars)`
+  - Fix: `Verify the key at https://laboratory.stellar.org`
+
+### Check: FACILITATOR_URL
+- **How:** Read `.env.local` (or `.env`) and check for `FACILITATOR_URL`
+- **PASS:** Variable is set and starts with `https://`
+  - Output: `[PASS] FACILITATOR_URL`
+- **FAIL:** Variable not set or empty
+  - Output: `[FAIL] Environment variable FACILITATOR_URL: Not set`
+  - Fix: `Add FACILITATOR_URL to .env.local. Testnet: https://channels.openzeppelin.com/x402/testnet`
+- **WARN:** Variable is set but doesn't start with `https://`
+  - Output: `[WARN] FACILITATOR_URL: Value doesn't look like a URL`
+  - Fix: `Expected format: https://channels.openzeppelin.com/x402/testnet`
+
+### Check: FACILITATOR_API_KEY
+- **How:** Read `.env.local` (or `.env`) and check for `FACILITATOR_API_KEY`
+- **PASS:** Variable is set and non-empty
+  - Output: `[PASS] FACILITATOR_API_KEY`
+- **FAIL:** Variable not set or empty
+  - Output: `[FAIL] Environment variable FACILITATOR_API_KEY: Not set`
+  - Fix: `Add FACILITATOR_API_KEY to .env.local (see .env.example). Get a key at: https://channels.openzeppelin.com/testnet/gen`
+
+## Category 2: Dependencies
+
+### Check: @x402/core installed
+- **How:** Read `package.json` and check `dependencies` for `@x402/core`
+- **PASS:** Package found in dependencies
+  - Output: `[PASS] @x402/core: Installed`
+- **FAIL:** Package not found
+  - Output: `[FAIL] Dependency @x402/core: Not installed`
+  - Fix: `Run npm install @x402/core`
+
+### Check: @x402/stellar installed
+- **How:** Read `package.json` and check `dependencies` for `@x402/stellar`
+- **PASS:** Package found in dependencies
+  - Output: `[PASS] @x402/stellar: Installed`
+- **FAIL:** Package not found
+  - Output: `[FAIL] Dependency @x402/stellar: Not installed`
+  - Fix: `Run npm install @x402/stellar`
+
+### Check: Framework-specific x402 package
+- **How:** Based on detected framework, check for the correct adapter package
+  - Next.js: check for `@x402/next` in dependencies
+  - Express: check for `@x402/express` in dependencies
+  - Fastify: skip (no official package -- uses @x402/core directly)
+  - Hono: check for `@x402/hono` in dependencies
+- **PASS:** Framework adapter package installed (or Fastify which doesn't need one)
+  - Output: `[PASS] Framework adapter: {package} installed` or `[PASS] Framework adapter: Fastify uses @x402/core directly (no dedicated package needed)`
+- **FAIL:** Framework adapter package missing
+  - Output: `[FAIL] Dependency {package}: Not installed`
+  - Fix: `Run npm install {package}`
+
+### Check: Dependency versions
+- **How:** Read `node_modules/@x402/core/package.json` for version
+- **PASS:** Version is 2.x
+  - Output: `[PASS] @x402/core version: {version}`
+- **WARN:** Version is below 2.0
+  - Output: `[WARN] @x402/core version {version}: Consider upgrading to 2.x`
+  - Fix: `Run npm install @x402/core@latest`
+
+## Category 3: Code Structure
+
+### Check: Route config file exists
+- **How:** Use Grep to find files containing `RoutesConfig` import
+- **PASS:** At least one file found
+  - Output: `[PASS] Route config: {file path}`
+- **FAIL:** No file found
+  - Output: `[FAIL] Route config: No routesConfig file found`
+  - Fix: `Run /x402:init to create route configuration`
+
+### Check: Server/middleware file exists
+- **How:** Use Grep to find files importing from `@x402/core/server` or `@x402/express` or `@x402/hono` or `@x402/next`
+- **PASS:** At least one file found
+  - Output: `[PASS] Server middleware: {file path}`
+- **FAIL:** No file found
+  - Output: `[FAIL] Server middleware: No x402 server file found`
+  - Fix: `Run /x402:init to scaffold the server middleware`
+
+### Check: ExactStellarScheme import path
+- **How:** Use Grep to find `ExactStellarScheme` imports
+- **PASS:** Import path is `@x402/stellar/exact/server`
+  - Output: `[PASS] ExactStellarScheme: Correctly imported from server path`
+- **WARN:** Import path is `@x402/stellar/exact/client` (wrong for server-side)
+  - Output: `[WARN] ExactStellarScheme: Imported from client path instead of server path`
+  - Fix: `Change import to: import { ExactStellarScheme } from "@x402/stellar/exact/server"`
+
+### Check: Protected endpoints in routesConfig
+- **How:** Read routesConfig file, count entries (keys matching `"METHOD /path"` pattern)
+- **PASS:** At least one route entry exists
+  - Output: `[PASS] Protected endpoints: {count} route(s) configured`
+- **WARN:** routesConfig is empty (no entries)
+  - Output: `[WARN] No protected endpoints in routesConfig`
+  - Fix: `Run /x402:add-paywall to protect an endpoint`
+
+### Check: Price format
+- **How:** Read routesConfig, check that price values start with `$`
+- **PASS:** All prices start with `$`
+  - Output: `[PASS] Price format: All prices use $ prefix`
+- **WARN:** Price without `$` prefix found
+  - Output: `[WARN] Price format: Found price without $ prefix`
+  - Fix: `Use "$0.001" format (dollar sign required)`
+
+## Category 4: Framework Detection
+
+### Check: Framework detected
+- **How:** Read `package.json` dependencies for `next`, `express`, `fastify`, `hono`
+- **PASS:** Exactly one supported framework detected
+  - Output: `[PASS] Framework detected: {name}`
+- **WARN:** Multiple frameworks detected
+  - Output: `[WARN] Multiple frameworks detected: {list}. Using {primary} based on priority.`
+- **FAIL:** No supported framework detected
+  - Output: `[FAIL] Framework: Could not detect framework from package.json`
+  - Fix: `Supported: Next.js, Express, Fastify, Hono`
+
+### Check: Adapter matches framework
+- **How:** Cross-check detected framework with imports in server file
+  - Next.js should import from `@x402/next` or use `withPayment`/`withX402`
+  - Express should import from `@x402/express`
+  - Fastify should import from `@x402/core/server` with custom adapter
+  - Hono should import from `@x402/hono`
+- **PASS:** Server file imports match detected framework
+  - Output: `[PASS] Adapter matches framework: {framework}`
+- **WARN:** Mismatch between framework and adapter imports
+  - Output: `[WARN] Framework mismatch: Detected {framework} but server imports from {package}`
+  - Fix: `Re-run /x402:init to regenerate correct adapter`
+
+## Summary Format
+
+After all checks, output a summary line:
+- If any FAIL: `{N} passed, {N} failed, {N} warnings. Fix the FAIL items above to complete your x402 setup.`
+- If no FAIL but has WARN: `{N} passed, {N} warnings. x402 is configured but review the warnings above.`
+- If all PASS: `All checks passed. x402 is ready.`

package/skills/x402-explain/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: x402-explain
+description: Generate a human-readable explanation of how x402 payment protection is wired in the current project.
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: [Read, Grep, Glob]
+---
+
+# /x402:explain
+
+> I'll analyze your codebase and explain exactly how x402 payment protection is wired -- which endpoints are protected, what the payment flow looks like, and where everything is configured.
+
+## Instructions
+
+Output is generated fresh on every invocation -- no caching. Read the codebase live to reflect its current state.
+
+### Step 1 -- Check for x402 setup
+
+Use Grep to check if `@x402/core` exists in `package.json` dependencies.
+
+If NOT found, output exactly:
+
+"No x402 payment protection detected in this project. Run /x402:init to get started."
+
+Then STOP. Do not proceed to further steps.
+
+### Step 2 -- Detect framework
+
+Check `package.json` dependencies for:
+- `"next"` -- Next.js
+- `"express"` -- Express
+- `"fastify"` -- Fastify
+- `"hono"` -- Hono
+
+If multiple frameworks detected, prefer: Next.js > Express > Fastify > Hono (by ecosystem size).
+
+### Step 3 -- Find configuration files
+
+- Use Grep to find files containing `RoutesConfig` import -> this is the routesConfig file path
+- Use Grep to find files containing `x402ResourceServer` or `paymentMiddleware` or `withPayment` or `withX402` -> this is the server/middleware file path
+- Use Grep to find files containing `// x402: payment-protected endpoint` -> these are protected route file paths
+- Read `.env.local` (or `.env` as fallback) for env var values. **Mask sensitive values:** show first 4 chars + `...` only. Never output full env var values.
+
+### Step 4 -- Read and analyze
+
+- Read the routesConfig file and parse route entries
+- For each route entry, extract: HTTP method, path, price, network, payTo address
+  - Mask payTo address: show first 4 chars + `...` + last 4 chars
+- Read the server/middleware file to understand the adapter pattern being used
+- Read protected route files (if any) to understand the wrapping pattern
+
+### Step 5 -- Generate output
+
+Produce the following markdown output. Use these exact section headings:
+
+```markdown
+## x402 Payment Protection Overview
+
+Framework: {detected framework}
+Adapter: {package name} ({version if detectable from node_modules})
+Network: {network from config, e.g., "stellar:testnet"}
+Receiving address: {first 4 chars}...{last 4 chars}
+
+## Protected Endpoints
+
+| Method | Path | Price | Asset | Network |
+|--------|------|-------|-------|---------|
+| GET | /api/content | $0.001 | USDC | stellar:testnet |
+| ... | ... | ... | ... | ... |
+```
+
+If no endpoints in routesConfig, output instead of the table:
+
+"No endpoints currently protected. Run /x402:add-paywall to protect an endpoint."
+
+```markdown
+## Payment Flow
+
+1. **Client sends request** to a protected endpoint (no payment header)
+2. **Server returns HTTP 402** with payment requirements in response headers
+3. **Client signs a payment** using their Stellar wallet (USDC amount from routesConfig)
+4. **Client retries** the same request with `X-Payment` header containing the signed payment
+5. **Facilitator verifies** the payment signature and settles the transaction on Stellar
+6. **Server returns the resource** after facilitator confirms payment
+
+## Framework: {name}
+```
+
+Include framework-specific description based on detected framework:
+
+**For Next.js:**
+```
+Adapter pattern: Inline handler wrapping with `withPayment()`/`withX402()`
+Each route handler is individually wrapped in its `route.ts` file.
+```
+
+**For Express:**
+```
+Adapter pattern: Global middleware via `paymentMiddleware()` from `@x402/express`
+All routes in routesConfig are automatically protected.
+```
+
+**For Fastify:**
+```
+Adapter pattern: Fastify plugin via custom `x402PaymentPlugin` using `@x402/core`
+All routes in routesConfig are automatically protected via onRequest hook.
+Note: Uses custom FastifyAdapter because @x402/fastify is not yet published on npm.
+```
+
+**For Hono:**
+```
+Adapter pattern: Global middleware via `paymentMiddleware()` from `@x402/hono`
+All routes in routesConfig are automatically protected.
+```
+
+```markdown
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| {config path} | Route pricing and environment configuration |
+| {server path} | x402 middleware/adapter setup |
+| .env.local | Environment variables (Stellar address, facilitator URL, API key) |
+```
+
+If Fastify is detected, add an additional row:
+```
+| {adapter path} | HTTPAdapter implementation (Fastify only) |
+```
+
+## Important Notes
+
+- The Payment Flow section is always the same 6-step list (from protocol spec, not derived from codebase analysis).
+- Mask all sensitive values: env vars show first 4 chars + `...`, Stellar addresses show first 4 chars + `...` + last 4 chars.
+- Output sections must follow the exact headings above (`## x402 Payment Protection Overview`, `## Protected Endpoints`, `## Payment Flow`, `## Framework: {name}`, `## Configuration Files`).
+- This command is read-only. Do not modify any files. Use only Read, Grep, and Glob tools.

package/skills/x402-init/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: x402-init
+description: Bootstrap x402 payment protection in a project. Detects framework, installs dependencies, creates config files, and scaffolds adapter.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[framework]"
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+---
+
+# /x402:init
+
+> Bootstrap x402 payment protection in your project. I'll detect your framework, install the right packages, and scaffold all config files.
+
+## Important Rules
+
+- Do NOT install `@x402/fastify` -- it does not exist on npm. For Fastify, use `@x402/core` directly with a custom adapter.
+- Server-side `ExactStellarScheme` import path is always `@x402/stellar/exact/server` (NOT `@x402/stellar/exact/client`).
+- All templates are in this skill's `templates/` directory. Read the template file and use its content as the basis for generated code.
+- Adapt import paths if needed based on project structure (e.g., relative paths based on file placement).
+
+## Step 1 -- Check for Existing x402 Setup (Idempotency)
+
+Before creating anything, check if x402 is already configured:
+
+1. **Check dependencies:** Use Grep to search for `@x402/core` in `package.json` dependencies
+2. **Check route config:** Use Glob to find files, then Grep to search for files containing a `RoutesConfig` import from `@x402/core/server`
+3. **Check env template:** Use Read to check if `.env.example` already contains `SERVER_STELLAR_ADDRESS`
+
+**If all 3 exist:**
+Output: `"x402 is already set up. {N} files exist, {N} skipped. Run /x402:debug to verify configuration."`
+STOP -- do not create or modify any files.
+
+**If some exist:**
+Report which pieces are already present. Skip those. Only create the missing pieces. Continue to the relevant steps below, skipping steps for components that already exist.
+
+## Step 2 -- Detect Framework
+
+**If `$ARGUMENTS` is provided** (e.g., `/x402:init express`), use that framework directly. Skip detection.
+
+**Otherwise, detect from `package.json`:**
+
+1. Read `package.json` in the current working directory
+2. If no `package.json` in the current directory, walk up parent directories to find the nearest one
+3. Check the `dependencies` object (not `devDependencies`) for framework packages
+4. Detection heuristics -- priority: Next.js > Express > Fastify > Hono (if multiple found, use the first match):
+   - `"next"` in dependencies -> **Next.js App Router**
+   - `"express"` in dependencies -> **Express**
+   - `"fastify"` in dependencies -> **Fastify**
+   - `"hono"` in dependencies -> **Hono**
+
+**Edge cases:**
+- If `@nestjs/core` is found in dependencies, warn: `"NestJS detected, using underlying Express/Fastify adapter"` and detect which underlying framework NestJS uses (check for `@nestjs/platform-express` or `@nestjs/platform-fastify`)
+- If no supported framework is detected, output: `"Could not detect framework from package.json. Supported: Next.js, Express, Fastify, Hono."` and STOP
+
+## Step 3 -- Detect Project Structure
+
+Determine where to place x402 files based on existing project conventions:
+
+1. Check if the project uses a `src/` directory pattern (e.g., `src/lib/`, `src/app/`, or other code under `src/`)
+2. If `src/` exists and contains code files: place x402 files in `src/lib/x402/`
+3. If no `src/` directory: place x402 files in `lib/x402/`
+4. For Next.js specifically: check for `app/` directory to confirm App Router usage
+
+Store the base directory (`src/lib` or `lib`) for use in subsequent steps.
+
+## Step 4 -- Install Dependencies
+
+Output: `"Installing @x402/core and @x402/stellar..."`
+
+Run the framework-specific install command via Bash:
+
+| Framework | Install Command |
+|-----------|----------------|
+| Next.js   | `npm install @x402/next @x402/core @x402/stellar` |
+| Express   | `npm install @x402/express @x402/core @x402/stellar` |
+| Fastify   | `npm install @x402/core @x402/stellar` |
+| Hono      | `npm install @x402/hono @x402/core @x402/stellar` |
+
+**Fastify note:** Do NOT install `@x402/fastify` -- it does not exist on npm. Only `@x402/core` and `@x402/stellar` are needed. The custom adapter code is scaffolded in Step 6.
+
+## Step 5 -- Scaffold Config Files
+
+1. Read the appropriate config template: `templates/{framework}/config.ts.md`
+   - Where `{framework}` is `next-app-router`, `express`, `fastify`, or `hono`
+2. Extract the TypeScript code from the template's fenced code block
+3. Write to `{base_dir}/x402/config.ts` (where `base_dir` was determined in Step 3)
+
+4. Read `templates/env-example.md`
+5. Extract the env content from the template's fenced code block
+6. Check if `.env.example` already exists at the project root:
+   - If it does NOT exist: create `.env.example` with the template content
+   - If it DOES exist: check if it already contains `SERVER_STELLAR_ADDRESS`. If not, append the x402 section to the existing file
+7. Output: `"Created .env.example with required variables. Copy to .env.local and fill in your values."`
+
+## Step 6 -- Scaffold Server/Middleware Files
+
+1. Read the appropriate server template: `templates/{framework}/server.ts.md`
+2. Extract the TypeScript code from the template's fenced code block
+3. Write to `{base_dir}/x402/server.ts`
+
+**For Fastify only -- also scaffold the adapter:**
+4. Read `templates/fastify/adapter.ts.md`
+5. Extract the TypeScript code from the template's fenced code block
+6. Write to `{base_dir}/x402/adapter.ts`
+
+## Step 7 -- Summary
+
+Count the files created during this run and output:
+
+`"x402 initialized. Created {N} files: {file list}"`
+
+List each file with its relative path from the project root, for example:
+
+```
+x402 initialized. Created 3 files:
+  - lib/x402/config.ts
+  - lib/x402/server.ts
+  - .env.example
+```
+
+For Fastify projects, the adapter file is also listed:
+
+```
+x402 initialized. Created 4 files:
+  - lib/x402/config.ts
+  - lib/x402/server.ts
+  - lib/x402/adapter.ts
+  - .env.example
+```

package/skills/x402-init/templates/env-example.md

@@ -0,0 +1,17 @@
+# .env.example Template
+
+```env
+# x402 Payment Configuration
+# See: https://docs.x402.org/getting-started/quickstart-for-sellers
+
+# Stellar public key (G...) that receives USDC payments
+SERVER_STELLAR_ADDRESS=
+
+# OpenZeppelin facilitator endpoint
+# Testnet: https://channels.openzeppelin.com/x402/testnet
+# Mainnet: https://channels.openzeppelin.com/x402/mainnet
+FACILITATOR_URL=https://channels.openzeppelin.com/x402/testnet
+
+# API key from https://channels.openzeppelin.com/testnet/gen
+FACILITATOR_API_KEY=
+```

package/skills/x402-init/templates/express/config.ts.md

@@ -0,0 +1,29 @@
+# Route Config Template
+
+```typescript
+import type { RoutesConfig } from "@x402/core/server";
+
+export const SERVER_ADDRESS = process.env.SERVER_STELLAR_ADDRESS!;
+export const FACILITATOR_URL =
+  process.env.FACILITATOR_URL ||
+  "https://channels.openzeppelin.com/x402/testnet";
+export const FACILITATOR_API_KEY = process.env.FACILITATOR_API_KEY!;
+
+export const PRICE = "$0.001";
+export const NETWORK = "stellar:testnet";
+
+export const routesConfig: RoutesConfig = {
+  // "GET /api/example": {
+  //   accepts: [
+  //     {
+  //       scheme: "exact",
+  //       price: PRICE,
+  //       network: NETWORK,
+  //       payTo: SERVER_ADDRESS,
+  //     },
+  //   ],
+  //   description: "Example protected endpoint",
+  //   mimeType: "application/json",
+  // },
+};
+```

package/skills/x402-init/templates/express/server.ts.md

@@ -0,0 +1,30 @@
+# Express Server Template
+
+Uses the official `@x402/express` package with `paymentMiddleware`.
+
+```typescript
+import { paymentMiddleware, x402ResourceServer } from "@x402/express";
+import { ExactStellarScheme } from "@x402/stellar/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import {
+  routesConfig,
+  FACILITATOR_URL,
+  FACILITATOR_API_KEY,
+  NETWORK,
+} from "./config";
+
+const facilitatorClient = new HTTPFacilitatorClient({
+  url: FACILITATOR_URL,
+  createAuthHeaders: async () => {
+    const headers = { Authorization: `Bearer ${FACILITATOR_API_KEY}` };
+    return { verify: headers, settle: headers, supported: headers };
+  },
+});
+
+const resourceServer = new x402ResourceServer(facilitatorClient).register(
+  NETWORK,
+  new ExactStellarScheme()
+);
+
+export const x402Middleware = paymentMiddleware(routesConfig, resourceServer);
+```

package/skills/x402-init/templates/fastify/adapter.ts.md

@@ -0,0 +1,66 @@
+# Fastify HTTPAdapter Template
+
+Custom adapter implementing `HTTPAdapter` from `@x402/core/server`.
+Required because `@x402/fastify` is not published on npm.
+
+```typescript
+import type { HTTPAdapter } from "@x402/core/server";
+import type { FastifyRequest } from "fastify";
+
+export class FastifyAdapter implements HTTPAdapter {
+  constructor(private req: FastifyRequest) {}
+
+  getHeader(name: string): string | undefined {
+    const value = this.req.headers[name.toLowerCase()];
+    return Array.isArray(value) ? value[0] : value ?? undefined;
+  }
+
+  getMethod(): string {
+    return this.req.method;
+  }
+
+  getPath(): string {
+    return this.req.url.split("?")[0];
+  }
+
+  getUrl(): string {
+    return `${this.req.protocol}://${this.req.hostname}${this.req.url}`;
+  }
+
+  getAcceptHeader(): string {
+    return this.req.headers.accept ?? "";
+  }
+
+  getUserAgent(): string {
+    return this.req.headers["user-agent"] ?? "";
+  }
+
+  getQueryParams(): Record<string, string | string[]> {
+    const url = new URL(this.getUrl());
+    const params: Record<string, string | string[]> = {};
+    url.searchParams.forEach((value, key) => {
+      const existing = params[key];
+      if (existing) {
+        params[key] = Array.isArray(existing)
+          ? [...existing, value]
+          : [existing, value];
+      } else {
+        params[key] = value;
+      }
+    });
+    return params;
+  }
+
+  getQueryParam(name: string): string | string[] | undefined {
+    const url = new URL(this.getUrl());
+    const values = url.searchParams.getAll(name);
+    if (values.length === 0) return undefined;
+    if (values.length === 1) return values[0];
+    return values;
+  }
+
+  getBody(): unknown {
+    return this.req.body;
+  }
+}
+```

package/skills/x402-init/templates/fastify/config.ts.md

@@ -0,0 +1,29 @@
+# Route Config Template
+
+```typescript
+import type { RoutesConfig } from "@x402/core/server";
+
+export const SERVER_ADDRESS = process.env.SERVER_STELLAR_ADDRESS!;
+export const FACILITATOR_URL =
+  process.env.FACILITATOR_URL ||
+  "https://channels.openzeppelin.com/x402/testnet";
+export const FACILITATOR_API_KEY = process.env.FACILITATOR_API_KEY!;
+
+export const PRICE = "$0.001";
+export const NETWORK = "stellar:testnet";
+
+export const routesConfig: RoutesConfig = {
+  // "GET /api/example": {
+  //   accepts: [
+  //     {
+  //       scheme: "exact",
+  //       price: PRICE,
+  //       network: NETWORK,
+  //       payTo: SERVER_ADDRESS,
+  //     },
+  //   ],
+  //   description: "Example protected endpoint",
+  //   mimeType: "application/json",
+  // },
+};
+```

package/skills/x402-init/templates/fastify/server.ts.md

@@ -0,0 +1,90 @@
+# Fastify Server Template
+
+Uses `@x402/core` directly because `@x402/fastify` is not published on npm.
+Implements a custom Fastify plugin with the `FastifyAdapter` class.
+
+```typescript
+import {
+  HTTPFacilitatorClient,
+  x402ResourceServer,
+  x402HTTPResourceServer,
+} from "@x402/core/server";
+import { ExactStellarScheme } from "@x402/stellar/exact/server";
+import { FastifyAdapter } from "./adapter";
+import {
+  routesConfig,
+  FACILITATOR_URL,
+  FACILITATOR_API_KEY,
+  NETWORK,
+} from "./config";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+
+let httpServer: x402HTTPResourceServer | null = null;
+let initPromise: Promise<void> | null = null;
+
+function getHTTPServer(): x402HTTPResourceServer {
+  if (!httpServer) {
+    const facilitatorClient = new HTTPFacilitatorClient({
+      url: FACILITATOR_URL,
+      createAuthHeaders: async () => {
+        const headers = { Authorization: `Bearer ${FACILITATOR_API_KEY}` };
+        return { verify: headers, settle: headers, supported: headers };
+      },
+    });
+    const resourceServer = new x402ResourceServer(facilitatorClient).register(
+      NETWORK,
+      new ExactStellarScheme()
+    );
+    httpServer = new x402HTTPResourceServer(resourceServer, routesConfig);
+  }
+  return httpServer;
+}
+
+async function ensureInitialized(): Promise<x402HTTPResourceServer> {
+  const server = getHTTPServer();
+  if (!initPromise) {
+    initPromise = server.initialize().catch((err) => {
+      initPromise = null;
+      throw err;
+    });
+  }
+  await initPromise;
+  return server;
+}
+
+export async function x402PaymentPlugin(fastify: FastifyInstance) {
+  fastify.addHook(
+    "onRequest",
+    async (req: FastifyRequest, reply: FastifyReply) => {
+      const server = await ensureInitialized();
+      const adapter = new FastifyAdapter(req);
+      const context = {
+        adapter,
+        path: adapter.getPath(),
+        method: adapter.getMethod(),
+        paymentHeader:
+          adapter.getHeader("x-payment") ??
+          adapter.getHeader("x-payment-signature"),
+      };
+      const result = await server.processHTTPRequest(context);
+
+      if (result.type === "payment-error") {
+        const { status, headers, body, isHtml } = result.response;
+        const responseBody = isHtml
+          ? (body as string)
+          : JSON.stringify(body ?? {});
+        const contentType = isHtml ? "text/html" : "application/json";
+        reply
+          .status(status)
+          .headers({ ...headers, "Content-Type": contentType })
+          .send(responseBody);
+        return reply;
+      }
+
+      if (result.type === "payment-verified") {
+        (req as any).__x402Result = result;
+      }
+    }
+  );
+}
+```