@payai/x402-hono-starter 1.0.0 → 1.0.1

package/NOTICE

@@ -1,2 +1,2 @@
 This package includes portions derived from coinbase/x402 (examples/typescript/servers/hono), Apache-2.0,
-commit f74bda39cc692f97e55fdb0bbfdff4a0f5e7f758. See LICENSE and upstream LICENSE notices.
+commit 7a83a1d57196b27ff9efe30c994f91eb50f60af5. See LICENSE and upstream LICENSE notices.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payai/x402-hono-starter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -39,4 +39,4 @@
   "config": {
     "x402HonoVersion": "2.2.0"
   }
-}
+}

package/template/.env-local

@@ -1,7 +1,5 @@
+EVM_ADDRESS=
+SVM_ADDRESS=
 FACILITATOR_URL=https://facilitator.payai.network
-NETWORK=solana-devnet
-ADDRESS=
 
-# required if using the Base mainnet facilitator
-CDP_API_KEY_ID="Coinbase Developer Platform Key"
-CDP_API_KEY_SECRET="Coinbase Developer Platform Key Secret"
+NETWORK=solana-devnet

package/template/README.md

@@ -1,36 +1,64 @@
-# x402-hono Example Server
+# @x402/hono Example Server
 
-This is an example Hono server that demonstrates how to use the `x402-hono` middleware to implement paywall functionality in your API endpoints.
+Hono server demonstrating how to protect API endpoints with a paywall using the `@x402/hono` middleware.
+
+```typescript
+import { Hono } from "hono";
+import { paymentMiddleware, x402ResourceServer } from "@x402/hono";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+
+const app = new Hono();
+
+app.use(
+  paymentMiddleware(
+    {
+      "GET /weather": {
+        accepts: { scheme: "exact", price: "$0.001", network: "eip155:84532", payTo: evmAddress },
+        description: "Weather data",
+        mimeType: "application/json",
+      },
+    },
+    new x402ResourceServer(new HTTPFacilitatorClient({ url: facilitatorUrl }))
+      .register("eip155:84532", new ExactEvmScheme()),
+  ),
+);
+
+app.get("/weather", c => c.json({ weather: "sunny", temperature: 70 }));
+```
 
 ## Prerequisites
 
 - Node.js v20+ (install via [nvm](https://github.com/nvm-sh/nvm))
 - pnpm v10 (install via [pnpm.io/installation](https://pnpm.io/installation))
-- A valid Ethereum address for receiving payments
-- Coinbase Developer Platform API Key & Secret (if accepting payments on Base mainnet)
--- get them here [https://portal.cdp.coinbase.com/projects](https://portal.cdp.coinbase.com/projects)
+- Valid EVM and SVM addresses for receiving payments
+- URL of a facilitator supporting the desired payment network, see [facilitator list](https://www.x402.org/ecosystem?category=facilitators)
 
 ## Setup
 
-1. Copy `.env-local` to `.env` and add your Ethereum address to receive payments:
+1. Copy `.env-local` to `.env`:
 
 ```bash
 cp .env-local .env
 ```
 
+and fill required environment variables:
+
+- `FACILITATOR_URL` - Facilitator endpoint URL
+- `EVM_ADDRESS` - Ethereum address to receive payments
+- `SVM_ADDRESS` - Solana address to receive payments
+
 2. Install and build all packages from the typescript examples root:
 
 ```bash
 cd ../../
-pnpm install
-pnpm build
+pnpm install && pnpm build
 cd servers/hono
 ```
 
 3. Run the server
 
 ```bash
-pnpm install
 pnpm dev
 ```
 
@@ -43,7 +71,6 @@ You can test the server using one of the example clients:
 ```bash
 cd ../clients/fetch
 # Ensure .env is setup
-pnpm install
 pnpm dev
 ```
 
@@ -52,7 +79,6 @@ pnpm dev
 ```bash
 cd ../clients/axios
 # Ensure .env is setup
-pnpm install
 pnpm dev
 ```
 
@@ -64,45 +90,94 @@ These clients will demonstrate how to:
 
 ## Example Endpoint
 
-The server includes a single example endpoint at `/weather` that requires a payment of $0.001 to access. The endpoint returns a simple weather report.
+The server includes a single example endpoint at `/weather` that requires a payment of 0.001 USDC on Base Sepolia or Solana Devnet to access. The endpoint returns a simple weather report.
 
 ## Response Format
 
 ### Payment Required (402)
 
+```
+HTTP/1.1 402 Payment Required
+Content-Type: application/json; charset=utf-8
+PAYMENT-REQUIRED: <base64-encoded JSON>
+
+{}
+```
+
+The `PAYMENT-REQUIRED` header contains base64-encoded JSON with the payment requirements.
+Note: `amount` is in atomic units (e.g., 1000 = 0.001 USDC, since USDC has 6 decimals):
+
 ```json
 {
-  "error": "X-PAYMENT header is required",
-  "paymentRequirements": {
-    "scheme": "exact",
-    "network": "base",
-    "maxAmountRequired": "1000",
-    "resource": "http://localhost:4021/weather",
-    "description": "",
-    "mimeType": "",
-    "payTo": "0xYourAddress",
-    "maxTimeoutSeconds": 60,
-    "asset": "0x...",
-    "outputSchema": null,
-    "extra": null
-  }
+  "x402Version": 2,
+  "error": "Payment required",
+  "resource": {
+    "url": "http://localhost:4021/weather",
+    "description": "Weather data",
+    "mimeType": "application/json"
+  },
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "eip155:84532",
+      "amount": "1000",
+      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+      "payTo": "0x1c47E9C085c2B7458F5b6C16cCBD65A65255a9f6",
+      "maxTimeoutSeconds": 300,
+      "extra": {
+        "name": "USDC",
+        "version": "2",
+        "resourceUrl": "http://localhost:4021/weather"
+      }
+    },
+    {
+      "scheme": "exact",
+      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+      "amount": "1000",
+      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+      "payTo": "FV6JPj6Fy12HG8SYStyHdcecXYmV1oeWERAokrh4GQ1n",
+      "maxTimeoutSeconds": 300,
+      "extra": {
+        "feePayer": "...",
+        "resourceUrl": "http://localhost:4021/weather"
+      }
+    }
+  ]
 }
 ```
 
 ### Successful Response
 
-```ts
-// Body
+```
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=utf-8
+PAYMENT-RESPONSE: <base64-encoded JSON>
+
+{"report":{"weather":"sunny","temperature":70}}
+```
+
+The `PAYMENT-RESPONSE` header contains base64-encoded JSON with the settlement details:
+
+```json
 {
-  "report": {
-    "weather": "sunny",
-    "temperature": 70
+  "success": true,
+  "transaction": "0x...",
+  "network": "eip155:84532",
+  "payer": "0x...",
+  "requirements": {
+    "scheme": "exact",
+    "network": "eip155:84532",
+    "amount": "1000",
+    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "payTo": "0x...",
+    "maxTimeoutSeconds": 300,
+    "extra": {
+      "name": "USDC",
+      "version": "2",
+      "resourceUrl": "http://localhost:4021/weather"
+    }
   }
 }
-// Headers
-{
-  "X-PAYMENT-RESPONSE": "..." // Encoded response object
-}
 ```
 
 ## Extending the Example
@@ -112,39 +187,68 @@ To add more paid endpoints, follow this pattern:
 ```typescript
 // First, configure the payment middleware with your routes
 app.use(
-  paymentMiddleware(payTo, {
-    // Define your routes and their payment requirements
-    "/your-endpoint": {
-      price: "$0.10",
-      network,
-    },
-    "/premium/*": {
-      price: {
-        amount: "100000",
-        asset: {
-          address: "0xabc",
-          decimals: 18,
-          eip712: {
-            name: "WETH",
-            version: "1",
-          },
+  paymentMiddleware(
+    {
+      "GET /your-endpoint": {
+        accepts: {
+          scheme: "exact",
+          price: "$0.10",
+          network: "eip155:84532",
+          payTo: evmAddress,
         },
+        description: "Your endpoint description",
+        mimeType: "application/json",
       },
-      network,
     },
-  }),
+    resourceServer,
+  ),
 );
 
 // Then define your routes as normal
-app.get("/your-endpoint", c => {
+app.get("/your-endpoint", (c) => {
   return c.json({
     // Your response data
   });
 });
+```
 
-app.get("/premium/content", c => {
-  return c.json({
-    content: "This is premium content",
-  });
-});
+**Network identifiers** use [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) format, for example:
+
+- `eip155:84532` — Base Sepolia
+- `eip155:8453` — Base Mainnet
+- `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` — Solana Devnet
+- `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` — Solana Mainnet
+
+## x402ResourceServer Config
+
+The `x402ResourceServer` uses a builder pattern to register payment schemes that declare how payments for each network should be processed:
+
+```typescript
+const resourceServer = new x402ResourceServer(facilitatorClient)
+  .register("eip155:*", new ExactEvmScheme()) // All EVM chains
+  .register("solana:*", new ExactSvmScheme()); // All SVM chains
+```
+
+## Facilitator Config
+
+The `HTTPFacilitatorClient` connects to a facilitator service that verifies and settles payments on-chain:
+
+```typescript
+const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
+
+// Or use multiple facilitators for redundancy
+const facilitatorClient = [
+  new HTTPFacilitatorClient({ url: primaryFacilitatorUrl }),
+  new HTTPFacilitatorClient({ url: backupFacilitatorUrl }),
+];
 ```
+
+## Next Steps
+
+See [Advanced Examples](../advanced/) for:
+
+- **Bazaar discovery** — make your API discoverable
+- **Dynamic pricing** — price based on request context
+- **Dynamic payTo** — route payments to different recipients
+- **Lifecycle hooks** — custom logic on verify/settle
+- **Custom tokens** — accept payments in custom tokens

package/template/index.ts

@@ -1,35 +1,53 @@
 import { config } from "dotenv";
+import { paymentMiddleware, x402ResourceServer } from "@x402/hono";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { ExactSvmScheme } from "@x402/svm/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
-import { paymentMiddleware, Network, Resource, SolanaAddress } from "x402-hono";
-
 config();
 
-const facilitatorUrl = process.env.FACILITATOR_URL as Resource;
-const payTo = process.env.ADDRESS as `0x${string}` | SolanaAddress;
-const network = process.env.NETWORK as Network;
-
-if (!facilitatorUrl || !payTo || !network) {
+const evmAddress = process.env.EVM_ADDRESS as `0x${string}`;
+const svmAddress = process.env.SVM_ADDRESS;
+if (!evmAddress || !svmAddress) {
   console.error("Missing required environment variables");
   process.exit(1);
 }
 
-const app = new Hono();
+const facilitatorUrl = process.env.FACILITATOR_URL;
+if (!facilitatorUrl) {
+  console.error("❌ FACILITATOR_URL environment variable is required");
+  process.exit(1);
+}
+const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
 
-console.log("Server is running");
+const app = new Hono();
 
 app.use(
   paymentMiddleware(
-    payTo,
     {
-      "/weather": {
-        price: "$0.001",
-        network,
+      "GET /weather": {
+        accepts: [
+          {
+            scheme: "exact",
+            price: "$0.001",
+            network: "eip155:84532",
+            payTo: evmAddress,
+          },
+          {
+            scheme: "exact",
+            price: "$0.001",
+            network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+            payTo: svmAddress,
+          },
+        ],
+        description: "Weather data",
+        mimeType: "application/json",
       },
     },
-    {
-      url: facilitatorUrl,
-    },
+    new x402ResourceServer(facilitatorClient)
+      .register("eip155:84532", new ExactEvmScheme())
+      .register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", new ExactSvmScheme()),
   ),
 );
 
@@ -46,3 +64,5 @@ serve({
   fetch: app.fetch,
   port: 4021,
 });
+
+console.log(`Server listening at http://localhost:4021`);

package/template/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "hono-server-example",
+  "name": "@x402/hono-server-example",
   "private": true,
   "type": "module",
   "scripts": {
@@ -10,22 +10,23 @@
     "lint:check": "eslint . --ext .ts"
   },
   "dependencies": {
-    "@hono/node-server": "^1.13.8",
-    "@x402/hono": "^2.2.0",
     "dotenv": "^16.4.7",
-    "hono": "^4.7.1"
+    "@hono/node-server": "^1.14.0",
+    "hono": "^4.7.1",
+    "@x402/hono": "^2.2.0"
   },
   "devDependencies": {
-    "tsup": "^7.2.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.0",
     "@eslint/js": "^9.24.0",
-    "eslint": "^9.24.0",
-    "eslint-plugin-jsdoc": "^50.6.9",
-    "eslint-plugin-prettier": "^5.2.6",
+    "@types/express": "^5.0.1",
     "@typescript-eslint/eslint-plugin": "^8.29.1",
     "@typescript-eslint/parser": "^8.29.1",
+    "eslint": "^9.24.0",
     "eslint-plugin-import": "^2.31.0",
-    "prettier": "3.5.2"
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-prettier": "^5.2.6",
+    "prettier": "3.5.2",
+    "tsup": "^7.2.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
   }
 }

package/template/tsconfig.json

@@ -11,5 +11,12 @@
     "baseUrl": ".",
     "types": ["node"]
   },
-  "include": ["index.ts"]
+  "include": [
+    "index.ts",
+    "bazaar.ts",
+    "custom-money-definition.ts",
+    "dynamic-pay-to.ts",
+    "dynamic-price.ts",
+    "hooks.ts"
+  ]
 }