x402-engineer 0.1.0

package/skills/x402-init/templates/hono/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/hono/server.ts.md

@@ -0,0 +1,31 @@
+# Hono Server Template
+
+Uses the official `@x402/hono` package with `paymentMiddleware`.
+
+```typescript
+import { paymentMiddleware } from "@x402/hono";
+import { x402ResourceServer } from "@x402/core/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { ExactStellarScheme } from "@x402/stellar/exact/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/next-app-router/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/next-app-router/server.ts.md

@@ -0,0 +1,31 @@
+# Next.js App Router Server Template
+
+Uses the official `@x402/next` package with `withX402` wrapper.
+
+```typescript
+import { withX402 } from "@x402/next";
+import { x402ResourceServer } from "@x402/core/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { ExactStellarScheme } from "@x402/stellar/exact/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 { withX402, routesConfig, resourceServer };
+```

package/skills/x402-stellar/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: x402-stellar
+description: >
+  Build pay-per-request APIs on Stellar using x402 protocol — HTTP 402 micropayments
+  with USDC. Activates on /x402:init, /x402:add-paywall, /x402:explain, /x402:debug
+  commands and when "x402, micropayment, paywall, pay per request, 402 payment,
+  USDC API, stellar payments, agent economy, monetize API, pay-per-use" mentioned.
+version: 1.0.0
+author: franco-stellar
+mcp-servers: []
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+tags: [stellar, x402, payments, web3, api, micropayments]
+triggers:
+  - /x402:init
+  - /x402:add-paywall
+  - /x402:explain
+  - /x402:debug
+  - x402
+---
+
+# x402-stellar
+
+> You are a **Stellar Payment Infrastructure Engineer** who has deployed x402 paywalls
+> to production, integrated with the OpenZeppelin facilitator, and debugged 402 response
+> headers across dozens of services. You speak from direct experience building
+> pay-per-request APIs on Stellar with USDC micropayments.
+>
+> **Expertise:** x402 protocol, Stellar SDK, USDC payments, Express middleware, payment
+> signing, facilitator integration, testnet/mainnet deployment.
+>
+> **Battle Scars:** missing facilitator API key causing silent 500s, wrong network
+> passphrase rejecting valid payments, clients not handling 402 responses correctly,
+> USDC trustline missing on the receiving account causing settlement failures,
+> confusing server vs client ExactStellarScheme imports.
+>
+> **Contrarian Opinions:**
+> - Don't use API keys when you can use x402 — let the protocol handle auth and billing.
+> - Don't build billing systems when USDC handles it — the blockchain IS your ledger.
+> - Don't gate content with subscriptions when micropayments per request are fairer.
+
+## Workflow
+
+### Step 1 — Detect Project Type
+
+Check the existing project structure to determine the framework in use.
+
+```bash
+# Check for Express, Fastify, or other frameworks
+cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"hono"|"koa"'
+```
+
+If no project exists, scaffold with Express (the only framework with official x402 middleware).
+
+### Step 2 — Install Dependencies
+
+```bash
+npm install @x402/express @x402/stellar @x402/core @stellar/stellar-sdk dotenv
+```
+
+For TypeScript projects, also install:
+
+```bash
+npm install -D typescript @types/express @types/node tsx
+```
+
+### Step 3 — Configure Environment
+
+Create a `.env` file with the required variables. See [references/setup.md](references/setup.md) for how to obtain each value.
+
+```env
+SERVER_STELLAR_ADDRESS=G...
+FACILITATOR_URL=https://channels.openzeppelin.com/x402/testnet
+FACILITATOR_API_KEY=your-api-key
+CLIENT_STELLAR_SECRET=S...
+```
+
+Run the dependency checker to validate:
+
+```bash
+node scripts/check-deps.js
+```
+
+### Step 4 — Add x402 Payment Middleware
+
+Add the payment middleware to your Express server. See [references/patterns.md](references/patterns.md) for the complete server pattern.
+
+Key points:
+- Create the `HTTPFacilitatorClient` with auth headers from your API key
+- Create the `x402ResourceServer` and register `stellar:testnet` with `ExactStellarScheme`
+- Define route pricing in the `paymentMiddleware` configuration object
+- Each route specifies scheme, price, network, and payTo address
+
+### Step 5 — Create Client with Payment Signer
+
+Build the client that handles 402 responses and signs payments. See [references/patterns.md](references/patterns.md) for the complete client pattern.
+
+Key points:
+- Use `createEd25519Signer` with the client's Stellar secret key
+- Register the signer with `ExactStellarScheme` on the client side
+- Use `x402HTTPClient` to parse 402 responses and create payment payloads
+- Resend the original request with the payment signature header
+
+### Step 6 — Test the 402 Flow
+
+1. Start the server
+2. Send a request without payment — expect HTTP 402
+3. Parse the 402 response headers for payment requirements
+4. Sign and send payment with the client
+5. Verify the response returns 200 with the expected data
+
+```bash
+# Start server
+npx tsx src/server.ts &
+
+# Test without payment (should get 402)
+curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:3000/api/endpoint
+
+# Run the full client flow
+npx tsx src/client.ts
+```
+
+## Common Mistakes
+
+| Mistake | Why It Fails | Fix |
+|---------|-------------|-----|
+| Missing facilitator API key | Server can't verify or settle payments; returns 500 instead of 402 | Generate a key at `channels.openzeppelin.com/testnet/gen` |
+| Wrong import path for ExactStellarScheme | Server and client export different classes with the same name | Server: `@x402/stellar/exact/server` — Client: `@x402/stellar/exact/client` |
+| Client using createStellarSigner for payment directly | That creates the signer, not the full payment flow | Use `x402Client` + `x402HTTPClient` + `ExactStellarScheme(signer)` together |
+| No USDC trustline on receiving account | Payment settlement fails because the account can't hold USDC | Add USDC trustline via Stellar Laboratory or SDK before accepting payments |
+| Hardcoding network to mainnet | Testnet payments fail silently because the network passphrase doesn't match | Use `"stellar:testnet"` for development and testing |
+| Not parsing x-payment header | Client can't extract payment requirements from the 402 response | Use `httpClient.getPaymentRequiredResponse()` to parse headers |
+| Forgetting `express.json()` middleware | Request body parsing fails on POST endpoints | Add `app.use(express.json())` before the payment middleware |
+| Price format without dollar sign | Middleware rejects the price configuration | Always use `"$0.001"` format with the dollar sign prefix |
+
+## References
+
+- [references/setup.md](references/setup.md) — Account creation, API keys, environment setup
+- [references/patterns.md](references/patterns.md) — Working server and client code patterns
+- [references/api.md](references/api.md) — Package API reference for @x402 modules

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

@@ -0,0 +1,237 @@
+# x402-stellar API Reference
+
+## @x402/express
+
+Express middleware for x402 payment verification and settlement.
+
+### `paymentMiddleware(routeConfig, resourceServer)`
+
+Creates Express middleware that intercepts requests matching configured routes and requires payment before allowing them through.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `routeConfig` | `Record<string, RoutePaymentConfig>` | Map of `"METHOD /path"` to payment configuration |
+| `resourceServer` | `x402ResourceServer` | Configured resource server instance |
+
+**RoutePaymentConfig:**
+
+```typescript
+interface RoutePaymentConfig {
+  accepts: PaymentAccept[];
+  description: string;
+  mimeType: string;
+}
+
+interface PaymentAccept {
+  scheme: "exact";          // Payment scheme identifier
+  price: string;            // Dollar-prefixed price: "$0.001"
+  network: string;          // Network identifier: "stellar:testnet"
+  payTo: string;            // Stellar public key (G...)
+}
+```
+
+**Returns:** Express middleware function.
+
+**Behavior:**
+- Requests to unconfigured routes pass through without payment.
+- Requests to configured routes without valid payment receive HTTP 402 with payment requirements in headers.
+- Requests with valid payment are verified, then passed to the next handler.
+- After the response is sent, payment is settled via the facilitator.
+
+### `x402ResourceServer`
+
+Manages payment scheme registration and facilitator communication.
+
+```typescript
+const resourceServer = new x402ResourceServer(facilitatorClient);
+```
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `register` | `(network: string, scheme: SchemeInstance) => this` | Register a payment scheme for a network. Returns `this` for chaining. |
+
+**Example:**
+
+```typescript
+const resourceServer = new x402ResourceServer(facilitatorClient)
+  .register("stellar:testnet", new ExactStellarScheme());
+```
+
+---
+
+## @x402/stellar
+
+Stellar-specific signers and payment scheme implementations.
+
+### `createEd25519Signer(secretKey)`
+
+Creates a Stellar Ed25519 signer from a secret key. Used on the **client side** to sign payment transactions.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `secretKey` | `string` | Stellar secret key (S..., 56 characters) |
+
+**Returns:** `Ed25519Signer` — signer object compatible with `ExactStellarScheme`.
+
+```typescript
+import { createEd25519Signer } from "@x402/stellar";
+
+const signer = createEd25519Signer("SCZANGBA5YHTNYVVV3C7CAZMCLP...");
+```
+
+### `ExactStellarScheme` (Server)
+
+**Import:** `@x402/stellar/exact/server`
+
+Server-side scheme for verifying and settling Stellar payments. Takes **no constructor arguments**.
+
+```typescript
+import { ExactStellarScheme } from "@x402/stellar/exact/server";
+
+const scheme = new ExactStellarScheme();
+// Register with resource server
+resourceServer.register("stellar:testnet", scheme);
+```
+
+### `ExactStellarScheme` (Client)
+
+**Import:** `@x402/stellar/exact/client`
+
+Client-side scheme for creating and signing Stellar payment transactions. Takes a **signer** as constructor argument.
+
+```typescript
+import { ExactStellarScheme } from "@x402/stellar/exact/client";
+import { createEd25519Signer } from "@x402/stellar";
+
+const signer = createEd25519Signer(process.env.CLIENT_STELLAR_SECRET!);
+const scheme = new ExactStellarScheme(signer);
+// Register with x402 client
+client.register("stellar:testnet", scheme);
+```
+
+> **Critical:** Do not confuse the server and client `ExactStellarScheme`. They share the same class name but have different import paths and different constructor signatures.
+
+---
+
+## @x402/core
+
+Core x402 protocol utilities shared between server and client.
+
+### `HTTPFacilitatorClient` (Server)
+
+**Import:** `@x402/core/server`
+
+HTTP client for communicating with the OpenZeppelin facilitator service.
+
+```typescript
+import { HTTPFacilitatorClient } from "@x402/core/server";
+
+const facilitatorClient = new HTTPFacilitatorClient({
+  url: "https://channels.openzeppelin.com/x402/testnet",
+  createAuthHeaders: async () => {
+    const headers = { Authorization: `Bearer ${apiKey}` };
+    return { verify: headers, settle: headers, supported: headers };
+  },
+});
+```
+
+**Constructor Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `string` | Facilitator service URL |
+| `createAuthHeaders` | `() => Promise<AuthHeaders>` | Async function returning auth headers for each operation |
+
+**AuthHeaders:**
+
+```typescript
+interface AuthHeaders {
+  verify: Record<string, string>;   // Headers for payment verification requests
+  settle: Record<string, string>;   // Headers for payment settlement requests
+  supported: Record<string, string>; // Headers for supported schemes requests
+}
+```
+
+### `x402Client` (Client)
+
+**Import:** `@x402/core/client`
+
+Core client for managing payment schemes and creating payments.
+
+```typescript
+import { x402Client } from "@x402/core/client";
+
+const client = new x402Client();
+```
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `register` | `(network: string, scheme: SchemeInstance) => this` | Register a payment scheme for a network |
+
+### `x402HTTPClient` (Client)
+
+**Import:** `@x402/core/client`
+
+HTTP-aware client that handles 402 response parsing and payment header encoding.
+
+```typescript
+import { x402HTTPClient } from "@x402/core/client";
+
+const httpClient = new x402HTTPClient(client);
+```
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getPaymentRequiredResponse` | `(headerGetter: (name: string) => string \| null) => PaymentRequired` | Parse 402 response headers into payment requirements |
+| `createPaymentPayload` | `(paymentRequired: PaymentRequired) => Promise<PaymentPayload>` | Create and sign a payment transaction |
+| `encodePaymentSignatureHeader` | `(payload: PaymentPayload) => Record<string, string>` | Encode payment into HTTP headers for the retry request |
+
+**Usage Flow:**
+
+```typescript
+// 1. Parse 402 headers
+const paymentRequired = httpClient.getPaymentRequiredResponse(
+  (name) => response.headers.get(name)
+);
+
+// 2. Create payment (signs Stellar transaction)
+const payload = await httpClient.createPaymentPayload(paymentRequired);
+
+// 3. Encode as headers
+const headers = httpClient.encodePaymentSignatureHeader(payload);
+
+// 4. Resend request with payment headers
+const paidResponse = await fetch(url, { headers: { ...originalHeaders, ...headers } });
+```
+
+---
+
+## Network Identifiers
+
+| Identifier | Network | Use Case |
+|------------|---------|----------|
+| `stellar:testnet` | Stellar Testnet | Development and testing |
+| `stellar:pubnet` | Stellar Mainnet | Production |
+
+## Price Format
+
+Prices are specified as dollar-prefixed strings:
+
+| Format | Value |
+|--------|-------|
+| `"$0.001"` | One-tenth of a cent |
+| `"$0.01"` | One cent |
+| `"$0.10"` | Ten cents |
+| `"$1.00"` | One dollar |
+
+The middleware converts these to the appropriate USDC amount for the Stellar transaction.