@x402sentinel/openclaw-sentinel 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @x402sentinel/openclaw-sentinel
+
+Budget enforcement & audit trails for OpenClaw x402 payments.
+
+Wraps every x402 HTTP payment your OpenClaw agent makes with Sentinel's
+spend controls and audit logging. No code changes to your agent — just
+install the plugin and set your limits.
+
+## Install
+
+```bash
+openclaw plugin install @x402sentinel/openclaw-sentinel
+```
+
+## Configure
+
+Add the plugin to your OpenClaw config:
+
+```json
+// ~/.openclaw/openclaw.json
+{
+  "plugins": {
+    "entries": {
+      "sentinel": {
+        "enabled": true,
+        "config": {
+          "apiKey": "sk_sentinel_...",
+          "agentId": "my-openclaw-agent",
+          "maxPerCall": 1.00,
+          "maxPerHour": 25.00,
+          "maxPerDay": 200.00
+        }
+      }
+    }
+  }
+}
+```
+
+### Config options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | *required* | Sentinel API key |
+| `apiUrl` | string | `https://sentinel.valeocash.com` | Sentinel dashboard URL |
+| `agentId` | string | `openclaw-agent` | Agent ID in audit trails |
+| `maxPerCall` | number | `1.00` | Max USDC per single x402 call |
+| `maxPerHour` | number | `25.00` | Max USDC per hour |
+| `maxPerDay` | number | `200.00` | Max USDC per day |
+
+## What it does
+
+- **Budget enforcement** — blocks payments exceeding per-call, hourly, or daily USDC limits before they execute
+- **Audit logging** — every x402 payment is logged to your Sentinel dashboard with agent ID, endpoint, amount, tx hash, and timing
+- **`sentinel_status` tool** — your agent can check its own budget status and remaining spend at any time
+
+## Dashboard
+
+View all payments, filter by agent or endpoint, and export CSV reports:
+
+https://sentinel.valeocash.com/dashboard
+
+## Get API Key
+
+1. Sign up at [sentinel.valeocash.com](https://sentinel.valeocash.com)
+2. Go to **Settings** → **Generate API Key**
+3. Add the key to your `openclaw.json` config
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { PluginApi, SentinelPluginConfig, PluginExports } from "./types";
+declare function activate(api: PluginApi, config: SentinelPluginConfig): void;
+declare function deactivate(): void;
+declare const plugin: PluginExports;
+export default plugin;
+export { activate, deactivate };

package/dist/index.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.deactivate = deactivate;
+const x402_1 = require("@x402sentinel/x402");
+const ONE_HOUR_MS = 60 * 60 * 1000;
+const ONE_DAY_MS = 24 * ONE_HOUR_MS;
+let active = false;
+function activate(api, config) {
+    const storage = new x402_1.ApiStorage({
+        baseUrl: `${config.apiUrl}/api/v1`,
+        apiKey: config.apiKey,
+    });
+    api.registerFetchInterceptor((originalFetch) => {
+        return (0, x402_1.wrapWithSentinel)(originalFetch, {
+            agentId: config.agentId,
+            budget: {
+                maxPerCall: String(config.maxPerCall),
+                maxPerHour: String(config.maxPerHour),
+                maxPerDay: String(config.maxPerDay),
+            },
+            audit: { storage },
+        });
+    });
+    api.registerTool({
+        name: "sentinel_status",
+        description: "Check current Sentinel budget status, spend totals, and remaining budget for this agent",
+        parameters: {},
+        async execute() {
+            const now = Date.now();
+            const [allTime, lastHour, lastDay] = await Promise.all([
+                storage.summarize({}),
+                storage.summarize({ startTime: now - ONE_HOUR_MS }),
+                storage.summarize({ startTime: now - ONE_DAY_MS }),
+            ]);
+            const hourlySpent = parseFloat(lastHour.total_spend) || 0;
+            const dailySpent = parseFloat(lastDay.total_spend) || 0;
+            return {
+                agentId: config.agentId,
+                totalSpent: allTime.total_spend,
+                totalTransactions: allTime.total_transactions,
+                uniqueEndpoints: allTime.unique_endpoints,
+                budgetRemaining: {
+                    hourly: Math.max(0, config.maxPerHour - hourlySpent).toFixed(2),
+                    daily: Math.max(0, config.maxPerDay - dailySpent).toFixed(2),
+                },
+                limits: {
+                    perCall: config.maxPerCall,
+                    perHour: config.maxPerHour,
+                    perDay: config.maxPerDay,
+                },
+                dashboard: `${config.apiUrl}/dashboard`,
+            };
+        },
+    });
+    active = true;
+    console.log(`[sentinel] Budget enforcement active: $${config.maxPerCall}/call, $${config.maxPerHour}/hr, $${config.maxPerDay}/day`);
+    console.log(`[sentinel] Audit dashboard: ${config.apiUrl}/dashboard`);
+}
+function deactivate() {
+    active = false;
+    console.log("[sentinel] Plugin deactivated");
+}
+const plugin = { activate, deactivate };
+exports.default = plugin;

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal OpenClaw plugin API type stubs.
+ *
+ * These describe only the surface area this plugin consumes,
+ * so we don't need @openclaw as a dependency.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: () => Promise<unknown>;
+}
+export interface PluginApi {
+    /** Wrap the agent's fetch function with a custom interceptor. */
+    registerFetchInterceptor(interceptor: (originalFetch: typeof fetch) => typeof fetch): void;
+    /** Expose a tool the agent can call during conversations. */
+    registerTool(tool: ToolDefinition): void;
+}
+export interface SentinelPluginConfig {
+    apiUrl: string;
+    apiKey: string;
+    agentId: string;
+    maxPerCall: number;
+    maxPerHour: number;
+    maxPerDay: number;
+}
+export interface PluginExports {
+    activate(api: PluginApi, config: SentinelPluginConfig): void;
+    deactivate(): void;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Minimal OpenClaw plugin API type stubs.
+ *
+ * These describe only the surface area this plugin consumes,
+ * so we don't need @openclaw as a dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/openclaw.plugin.json

@@ -0,0 +1,39 @@
+{
+  "id": "sentinel",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiUrl": {
+        "type": "string",
+        "default": "https://sentinel.valeocash.com",
+        "description": "Sentinel dashboard URL"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Sentinel API key (from sentinel.valeocash.com/dashboard/settings)"
+      },
+      "agentId": {
+        "type": "string",
+        "default": "openclaw-agent",
+        "description": "Agent identifier for audit trails"
+      },
+      "maxPerCall": {
+        "type": "number",
+        "default": 1.0,
+        "description": "Max USDC per single x402 call"
+      },
+      "maxPerHour": {
+        "type": "number",
+        "default": 25.0,
+        "description": "Max USDC per hour"
+      },
+      "maxPerDay": {
+        "type": "number",
+        "default": 200.0,
+        "description": "Max USDC per day"
+      }
+    },
+    "required": ["apiKey"]
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@x402sentinel/openclaw-sentinel",
+  "version": "0.1.0",
+  "description": "Budget enforcement & audit trails for OpenClaw x402 payments",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@x402sentinel/x402": ">=0.1.2"
+  },
+  "devDependencies": {
+    "@x402sentinel/x402": "^0.1.2",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "x402",
+    "sentinel",
+    "audit",
+    "compliance",
+    "budget",
+    "ai-agents",
+    "usdc"
+  ],
+  "author": "Valeo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/valeo-cash/Sentinel"
+  },
+  "homepage": "https://sentinel.valeocash.com"
+}