@4mica/x402 0.1.0

package/.eslintrc.cjs

@@ -0,0 +1,29 @@
+module.exports = {
+  root: true,
+  env: {
+    es2020: true,
+    node: true,
+  },
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    sourceType: "module",
+    ecmaVersion: 2020,
+    project: "./tsconfig.json",
+  },
+  plugins: ["@typescript-eslint"],
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "eslint-config-prettier",
+  ],
+  rules: {
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+    ],
+    "@typescript-eslint/no-var-requires": "off",
+  },
+  ignorePatterns: ["dist", "node_modules"],
+};

package/.prettierignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+coverage

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "semi": false
+}

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.3.0
+- Breaking: include `reqId` in `PaymentGuaranteeRequestClaims` and signing payloads (EIP-712/EIP-191).
+- Breaking: X402 envelopes now emit `req_id` and `TabResponse` exposes `nextReqId` for claim building.
+- Fix: `listRecipientTabs` query parameter uses `settlement_status` to match core API.
+- Improve: RPC admin endpoints return typed `UserSuspensionStatus`/`AdminApiKey*` models and errors carry status metadata.
+- Fix: contract gateway disambiguates overloaded withdrawal functions for ethers v6.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 4Mica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,389 @@
+# @4mica/x402
+
+Express middleware and client integration for the x402 Payment Protocol with 4mica credit flow support. This package provides batteries-included middleware for adding 4mica payment requirements to your Express.js applications, with automatic facilitator and scheme registration.
+
+## Installation
+
+```bash
+pnpm install @4mica/x402
+```
+
+## Quick Start (Server)
+
+```typescript
+import express from "express";
+import { paymentMiddlewareFromConfig } from "@4mica/x402/server/express";
+
+const app = express();
+app.use(express.json());
+
+// Apply the payment middleware - facilitator and scheme are automatically configured
+app.use(
+  paymentMiddlewareFromConfig(
+    {
+      "GET /premium-content": {
+        accepts: {
+          scheme: "4mica-credit",
+          price: "$0.10",
+          network: "eip155:11155111", // Ethereum Sepolia
+          payTo: "0xYourAddress",
+        },
+        description: "Access to premium content",
+      },
+    },
+    // Payment tab config
+    {
+      advertisedEndpoint: "https://api.example.com/tabs/open",
+    }
+  )
+);
+
+// Implement your protected route
+app.get("/premium-content", (req, res) => {
+  res.json({ message: "This is premium content behind a paywall" });
+});
+
+app.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+});
+```
+
+## Quick Start (Client)
+
+### Using with Fetch
+
+Use with `@x402/fetch` for automatic payment handling:
+
+```typescript
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { FourMicaEvmScheme } from "@4mica/x402/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Create an EVM account
+const account = privateKeyToAccount("0xYourPrivateKey");
+
+// Create the 4mica scheme client
+const scheme = await FourMicaEvmScheme.create(account);
+
+// Wrap fetch with payment handling
+const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
+  schemes: [
+    {
+      network: "eip155:11155111", // Ethereum Sepolia
+      client: scheme,
+    },
+  ],
+});
+
+// Make requests - payments are handled automatically
+const response = await fetchWithPayment("https://api.example.com/premium-content");
+const data = await response.json();
+console.log(data);
+```
+
+### Using with Axios
+
+Use with `@x402/axios` for Axios-based applications:
+
+```typescript
+import axios from "axios";
+import { wrapAxiosWithPaymentFromConfig } from "@x402/axios";
+import { FourMicaEvmScheme } from "@4mica/x402/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Create an EVM account
+const account = privateKeyToAccount("0xYourPrivateKey");
+
+// Create the 4mica scheme client
+const scheme = await FourMicaEvmScheme.create(account);
+
+// Wrap axios instance with payment handling
+const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
+  schemes: [
+    {
+      network: "eip155:11155111", // Ethereum Sepolia
+      client: scheme,
+    },
+  ],
+});
+
+// Make requests - payments are handled automatically
+const response = await api.get("https://api.example.com/premium-content");
+const data = response.data;
+console.log(data);
+```
+
+## Server Configuration
+
+### `paymentMiddlewareFromConfig(routes, tabConfig, ...options)`
+
+The recommended middleware factory for most use cases. Automatically configures the 4mica facilitator and registers the `FourMicaEvmScheme` for all supported networks.
+
+#### Parameters
+
+1. **`routes`** (required): Route configurations for protected endpoints
+
+```typescript
+{
+  "GET /path": {
+    accepts: {
+      scheme: "4mica-credit",
+      price: "$0.10",
+      network: "eip155:11155111", // or "eip155:80002" for Polygon Amoy
+      payTo: "0xRecipientAddress",
+    },
+    description: "What the user is paying for",
+  }
+}
+```
+
+2. **`tabConfig`** (required): Payment tab configuration
+
+```typescript
+{
+  // Full URL endpoint for opening payment tabs
+  // This is injected into paymentRequirements.extra and clients use it to open tabs
+  advertisedEndpoint: "https://api.example.com/tabs/open",
+  
+  // Lifetime of payment tabs in seconds
+  ttlSeconds: 3600, // optional, defaults to facilitator's default
+}
+```
+
+3. **`facilitatorClients`** (optional): Additional facilitator client(s) for other payment schemes
+4. **`schemes`** (optional): Additional scheme registrations for other networks/schemes
+5. **`paywallConfig`** (optional): Configuration for the built-in paywall UI
+6. **`paywall`** (optional): Custom paywall provider
+7. **`syncFacilitatorOnStart`** (optional): Whether to sync with facilitator on startup (defaults to true)
+
+#### Supported Networks
+
+- `eip155:11155111` - Ethereum Sepolia
+- `eip155:80002` - Polygon Amoy
+
+### Advanced Server Usage
+
+For advanced scenarios where you need additional payment schemes or custom configuration:
+
+#### Using `paymentMiddleware` with Custom Server
+
+```typescript
+import { paymentMiddleware } from "@4mica/x402/server/express";
+import { 
+  x402ResourceServer,
+  FourMicaFacilitatorClient,
+} from "@4mica/x402/server";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+
+// Create 4mica facilitator
+const fourMicaFacilitator = new FourMicaFacilitatorClient();
+
+// Optionally add other facilitators/schemes for additional payment methods
+const otherFacilitator = new HTTPFacilitatorClient({ 
+  url: "https://other-facilitator.example.com" 
+});
+
+// Create resource server with facilitators and additional schemes
+// The middleware will auto-register FourMicaEvmScheme
+const resourceServer = new x402ResourceServer([
+  fourMicaFacilitator,
+  otherFacilitator,
+])
+  .register("eip155:8453", new ExactEvmScheme()); // Add Base mainnet with exact scheme
+
+app.use(
+  paymentMiddleware(
+    routes,
+    resourceServer,
+    {
+      advertisedEndpoint: "https://api.example.com/tabs/open",
+      ttlSeconds: 3600,
+    },
+    paywallConfig
+  )
+);
+```
+
+#### Using `paymentMiddlewareFromHTTPServer` with HTTP Hooks
+
+```typescript
+import { paymentMiddlewareFromHTTPServer } from "@4mica/x402/server/express";
+import {
+  x402ResourceServer,
+  x402HTTPResourceServer,
+  FourMicaFacilitatorClient,
+} from "@4mica/x402/server";
+
+// Create 4mica facilitator
+const fourMicaFacilitator = new FourMicaFacilitatorClient();
+
+// The middleware will auto-register FourMicaEvmScheme
+const resourceServer = new x402ResourceServer(fourMicaFacilitator);
+
+const httpServer = new x402HTTPResourceServer(resourceServer, routes)
+  .onProtectedRequest((context) => {
+    console.log("Protected request:", context.path);
+  });
+
+app.use(
+  paymentMiddlewareFromHTTPServer(
+    httpServer,
+    {
+      advertisedEndpoint: "https://api.example.com/tabs/open",
+      ttlSeconds: 3600,
+    },
+    paywallConfig
+  )
+);
+```
+
+## Client Configuration
+
+### Multi-Network Client Setup
+
+```typescript
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { FourMicaEvmScheme } from "@4mica/x402/client";
+
+const sepoliaScheme = await FourMicaEvmScheme.create(sepoliaAccount);
+const amoyScheme = await FourMicaEvmScheme.create(amoyAccount);
+
+const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
+  schemes: [
+    {
+      network: "eip155:11155111", // Ethereum Sepolia
+      client: sepoliaScheme,
+    },
+    {
+      network: "eip155:80002", // Polygon Amoy
+      client: amoyScheme,
+    },
+  ],
+});
+```
+
+### Using Builder Pattern
+
+```typescript
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { FourMicaEvmScheme } from "@4mica/x402/client";
+
+const scheme = await FourMicaEvmScheme.create(account);
+
+const client = new x402Client()
+  .register("eip155:11155111", scheme);
+
+const fetchWithPayment = wrapFetchWithPayment(fetch, client);
+```
+
+## Complete Example
+
+### Server
+
+```typescript
+import express from "express";
+import { paymentMiddlewareFromConfig } from "@4mica/x402/server/express";
+
+const app = express();
+app.use(express.json());
+
+app.use(
+  paymentMiddlewareFromConfig(
+    {
+      "GET /api/data": {
+        accepts: {
+          scheme: "4mica-credit",
+          price: "$0.05",
+          network: "eip155:11155111",
+          payTo: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
+        },
+        description: "API data access",
+      },
+      "POST /api/compute": {
+        accepts: {
+          scheme: "4mica-credit",
+          price: "$0.20",
+          network: "eip155:11155111",
+          payTo: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
+        },
+        description: "Computation service",
+      },
+    },
+    {
+      advertisedEndpoint: "https://api.example.com/tabs/open",
+      ttlSeconds: 7200, // 2 hours
+    }
+  )
+);
+
+app.get("/api/data", (req, res) => {
+  res.json({ data: "Premium data content" });
+});
+
+app.post("/api/compute", (req, res) => {
+  res.json({ result: "Computation complete" });
+});
+
+app.listen(3000);
+```
+
+### Client
+
+```typescript
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { FourMicaEvmScheme } from "@4mica/x402/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+async function main() {
+  const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+  const scheme = await FourMicaEvmScheme.create(account);
+
+  const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
+    schemes: [
+      {
+        network: "eip155:11155111",
+        client: scheme,
+      },
+    ],
+  });
+
+  // Fetch premium data - payment handled automatically
+  const dataResponse = await fetchWithPayment("https://api.example.com/api/data");
+  const data = await dataResponse.json();
+  console.log("Data:", data);
+
+  // Make computation request - payment handled automatically
+  const computeResponse = await fetchWithPayment("https://api.example.com/api/compute", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ input: "some data" }),
+  });
+  const result = await computeResponse.json();
+  console.log("Result:", result);
+}
+
+main();
+```
+
+## How It Works
+
+1. **Server Setup**: The middleware automatically registers the `FourMicaEvmScheme` and injects the 4mica facilitator client, so you don't need to configure them manually.
+
+2. **Tab Management**: When a client requests a protected resource, the middleware handles the tab lifecycle:
+   - The `advertisedEndpoint` is injected into `paymentRequirements.extra.tabEndpoint`
+   - Clients use this endpoint to open payment tabs
+   - The middleware automatically processes tab opening requests when they arrive at the advertised endpoint
+
+3. **Payment Flow**:
+   - Client makes initial request to protected resource
+   - Server responds with `402 Payment Required` including payment requirements
+   - Client requests a tab from the advertised endpoint
+   - Client signs a payment guarantee using the 4mica SDK
+   - Client retries the request with the payment payload
+   - Server verifies and settles the payment via the 4mica facilitator
+   - Server returns the protected resource
+
+## License
+
+MIT

package/demo/.env.example

@@ -0,0 +1,8 @@
+# Server Configuration
+PORT=3000
+PAY_TO_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
+ADVERTISED_ENDPOINT=http://localhost:3000/payment/tab
+
+# Client Configuration
+PRIVATE_KEY=0xYourPrivateKeyHere
+API_URL=http://localhost:3000

package/demo/README.md

@@ -0,0 +1,125 @@
+# @4mica/x402 Demo
+
+This demo shows how to use `@4mica/x402` to protect an API endpoint with 4mica payments.
+
+## Setup
+
+1. **Install dependencies**:
+
+First, build the parent package:
+
+```bash
+cd ..
+yarn install
+yarn build
+```
+
+Then install demo dependencies:
+
+```bash
+cd demo
+yarn install
+```
+
+2. **Configure environment variables**:
+
+Copy the example file and edit it:
+
+```bash
+cp .env.example .env
+# Edit .env with your private key and settings
+```
+
+Required variables:
+- `PRIVATE_KEY`: Your Ethereum private key (with 0x prefix) for Sepolia testnet
+- `PAY_TO_ADDRESS`: Address that will receive payments (optional, defaults to a test address)
+
+## Running the Demo
+
+### Terminal 1: Start the server
+
+From the demo directory:
+
+```bash
+yarn server
+```
+
+Or from the package root:
+
+```bash
+yarn demo:server
+```
+
+You should see:
+```
+x402 Demo Server running on http://localhost:3000
+Protected endpoint: http://localhost:3000/api/premium-data
+Payment required: $0.05 (4mica credit on Sepolia)
+```
+
+### Terminal 2: Run the client
+
+The client will automatically load environment variables from `.env`:
+
+From the demo directory:
+
+```bash
+yarn client
+```
+
+Or from the package root:
+
+```bash
+yarn demo:client
+```
+
+You can also set PRIVATE_KEY inline:
+
+```bash
+PRIVATE_KEY=0xYourPrivateKey yarn client
+```
+
+## What Happens
+
+1. **Server** starts with one protected endpoint: `GET /api/premium-data`
+   - Requires a payment of $0.05 in 4mica credits on Sepolia
+   - Uses x402 payment protocol
+
+2. **Client** makes a request to the protected endpoint:
+   - First receives `402 Payment Required` response
+   - Automatically opens a payment tab via the 4mica facilitator
+   - Signs and submits the payment
+   - Retries the request with payment proof
+   - Receives the protected data
+
+3. **Payment Flow**:
+   ```
+   Client → GET /api/premium-data
+          ← 402 Payment Required (with payment requirements)
+   
+   Client → POST /payment/tab (open payment tab)
+          ← 200 OK (tab details)
+   
+   Client → Signs payment guarantee (via 4mica SDK)
+   
+   Client → GET /api/premium-data (with payment proof)
+          ← 200 OK (protected data)
+   ```
+
+## Testing Without Running the Client
+
+You can also test the server manually using curl:
+
+```bash
+# Check server status
+curl http://localhost:3000/
+
+# Try to access protected endpoint (will return 402)
+curl -v http://localhost:3000/api/premium-data
+```
+
+## Notes
+
+- Make sure your account has sufficient balance on Sepolia testnet
+- The demo uses the default 4mica facilitator configuration
+- Tab TTL is set to 1 hour (3600 seconds)

package/demo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@4mica/x402-demo",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "server": "tsx src/server.ts",
+    "client": "tsx src/client.ts",
+    "deposit": "tsx src/deposit.ts",
+    "dev": "tsx watch src/server.ts"
+  },
+  "dependencies": {
+    "@4mica/sdk": "file:../../../../../ts-sdk-4mica",
+    "@4mica/x402": "file:..",
+    "@x402/fetch": "^2.2.0",
+    "dotenv": "^16.4.7",
+    "express": "^5.2.1",
+    "viem": "^2.21.54"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.3.3"
+  }
+}

package/demo/src/client.ts

@@ -0,0 +1,54 @@
+import 'dotenv/config'
+import { wrapFetchWithPaymentFromConfig } from '@x402/fetch'
+import { FourMicaEvmScheme } from '@4mica/x402/client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+async function main() {
+  const privateKey = process.env.PRIVATE_KEY
+  if (!privateKey || !privateKey.startsWith('0x')) {
+    console.error('Error: PRIVATE_KEY environment variable must be set and start with 0x')
+    console.error('Example: PRIVATE_KEY=0x1234... yarn client')
+    process.exit(1)
+  }
+
+  const apiUrl = process.env.API_URL || 'http://localhost:3000'
+  const endpoint = `${apiUrl}/api/premium-data`
+
+  console.log('Initializing x402 client...')
+  console.log(`Target endpoint: ${endpoint}`)
+
+  const account = privateKeyToAccount(privateKey as `0x${string}`)
+  console.log(`Using account: ${account.address}`)
+
+  const scheme = await FourMicaEvmScheme.create(account)
+
+  const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
+    schemes: [
+      {
+        network: 'eip155:11155111', // Ethereum Sepolia
+        client: scheme,
+      },
+    ],
+  })
+
+  console.log('\nMaking request to protected endpoint...')
+
+  try {
+    const response = await fetchWithPayment(endpoint)
+    const data = await response.json()
+
+    console.log('Request successful!')
+    console.log('Response:', JSON.stringify(data, null, 2))
+  } catch (error) {
+    console.error('Request failed:', error)
+    if (error instanceof Error) {
+      console.error('Message:', error.message)
+    }
+    process.exit(1)
+  }
+}
+
+main().catch((error) => {
+  console.error('Unhandled error:', error)
+  process.exit(1)
+})