@payai/x402-express-starter 0.1.2 → 1.3.0

package/NOTICE

@@ -1,2 +1,2 @@
 This package includes portions derived from coinbase/x402 (examples/typescript/servers/express), Apache-2.0,
-commit 4ec9c29df28a54e5ec151d4a8000935e96f4c3ee. See LICENSE and upstream LICENSE notices.
+commit 3f9cdc54d687333359841c44c326fcb5b39b2828. See LICENSE and upstream LICENSE notices.

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@payai/x402-express-starter",
-  "version": "0.1.2",
+  "version": "1.3.0",
   "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "description": "Create an x402 Express server in less than 2 minutes!",
   "type": "module",
   "bin": {
@@ -30,9 +34,14 @@
   "author": "PayAI",
   "repository": {
     "type": "git",
-    "url": "https://github.com/PayAINetwork/x402-express-starter"
+    "url": "git+https://github.com/PayAINetwork/x402-express-starter.git"
   },
   "config": {
-    "x402ExpressVersion": "0.6.5"
+    "x402ExpressVersion": "2.2.0",
+    "x402FetchVersion": "1.1.0",
+    "x402EvmVersion": "2.2.0",
+    "x402SvmVersion": "2.2.0",
+    "x402CoreVersion": "2.2.0",
+    "x402ExtensionsVersion": "2.2.0"
   }
 }

package/template/.env-local

@@ -1,7 +1,3 @@
-FACILITATOR_URL=https://facilitator.payai.network
-NETWORK=base-sepolia
-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"
+EVM_ADDRESS=
+SVM_ADDRESS=
+FACILITATOR_URL=https://facilitator.payai.network

package/template/README.md

@@ -1,34 +1,62 @@
-# x402-express Example Server
+# @x402/express Example Server
 
-This is an example Express.js server that demonstrates how to use the `x402-express` middleware to implement paywall functionality in your API endpoints.
+Express.js server demonstrating how to protect API endpoints with a paywall using the `@x402/express` middleware.
+
+```typescript
+import express from "express";
+import { paymentMiddleware, x402ResourceServer } from "@x402/express";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+
+const app = express();
+
+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", (req, res) => res.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/express
 ```
 
 3. Run the server
 ```bash
-pnpm install
 pnpm dev
 ```
 
@@ -40,7 +68,6 @@ You can test the server using one of the example clients:
 ```bash
 cd ../clients/fetch
 # Ensure .env is setup
-pnpm install
 pnpm dev
 ```
 
@@ -48,7 +75,6 @@ pnpm dev
 ```bash
 cd ../clients/axios
 # Ensure .env is setup
-pnpm install
 pnpm dev
 ```
 
@@ -59,43 +85,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
@@ -106,28 +183,19 @@ To add more paid endpoints, follow this pattern:
 // First, configure the payment middleware with your routes
 app.use(
   paymentMiddleware(
-    payTo,
     {
-      // Define your routes and their payment requirements
       "GET /your-endpoint": {
-        price: "$0.10",
-        network: "base-sepolia",
-      },
-      "/premium/*": {
-        price: {
-          amount: "100000",
-          asset: {
-            address: "0xabc",
-            decimals: 18,
-            eip712: {
-              name: "WETH",
-              version: "1",
-            },
-          },
+        accepts: {
+          scheme: "exact",
+          price: "$0.10",
+          network: "eip155:84532",
+          payTo: evmAddress,
         },
-        network: "base-sepolia",
+        description: "Your endpoint description",
+        mimeType: "application/json",
       },
     },
+    resourceServer,
   ),
 );
 
@@ -137,10 +205,43 @@ app.get("/your-endpoint", (req, res) => {
     // Your response data
   });
 });
+```
 
-app.get("/premium/content", (req, res) => {
-  res.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,51 +1,52 @@
 import { config } from "dotenv";
 import express from "express";
-import { paymentMiddleware, Resource, type SolanaAddress } from "x402-express";
+import { paymentMiddleware, x402ResourceServer } from "@x402/express";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { ExactSvmScheme } from "@x402/svm/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
 config();
 
-const facilitatorUrl = process.env.FACILITATOR_URL as Resource;
-const payTo = process.env.ADDRESS as `0x${string}` | SolanaAddress;
-
-if (!facilitatorUrl || !payTo) {
+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 facilitatorUrl = process.env.FACILITATOR_URL;
+if (!facilitatorUrl) {
+  console.error("❌ FACILITATOR_URL environment variable is required");
+  process.exit(1);
+}
+const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
+
 const app = express();
 
 app.use(
   paymentMiddleware(
-    payTo,
     {
       "GET /weather": {
-        // USDC amount in dollars
-        price: "$0.001",
-        // network: "base" // uncomment for Base mainnet
-        // network: "solana" // uncomment for Solana mainnet
-        network: "base-sepolia",
-      },
-      "/premium/*": {
-        // Define atomic amounts in any EIP-3009 token
-        price: {
-          amount: "100000",
-          asset: {
-            address: "0xabc",
-            decimals: 18,
-            // omit eip712 for Solana
-            eip712: {
-              name: "WETH",
-              version: "1",
-            },
+        accepts: [
+          {
+            scheme: "exact",
+            price: "$0.001",
+            network: "eip155:84532",
+            payTo: evmAddress,
+          },
+          {
+            scheme: "exact",
+            price: "$0.001",
+            network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+            payTo: svmAddress,
           },
-        },
-        // network: "base" // uncomment for Base mainnet
-        // network: "solana" // uncomment for Solana mainnet
-        network: "base-sepolia",
+        ],
+        description: "Weather data",
+        mimeType: "application/json",
       },
     },
-    {
-      url: facilitatorUrl,
-    },
+    new x402ResourceServer(facilitatorClient)
+      .register("eip155:84532", new ExactEvmScheme())
+      .register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", new ExactSvmScheme()),
   ),
 );
 
@@ -58,12 +59,6 @@ app.get("/weather", (req, res) => {
   });
 });
 
-app.get("/premium/content", (req, res) => {
-  res.send({
-    content: "This is premium content",
-  });
-});
-
 app.listen(4021, () => {
   console.log(`Server listening at http://localhost:${4021}`);
 });

package/template/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "express-server-example",
+  "name": "@x402/express-server-example",
   "private": true,
   "type": "module",
   "scripts": {
@@ -12,7 +12,11 @@
   "dependencies": {
     "dotenv": "^16.4.7",
     "express": "^4.18.2",
-    "x402-express": "^0.6.5"
+    "@x402/express": "^2.2.0",
+    "@x402/evm": "^2.2.0",
+    "@x402/svm": "^2.2.0",
+    "@x402/core": "^2.2.0",
+    "@x402/extensions": "^2.2.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
@@ -28,4 +32,4 @@
     "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"
+  ]
 }