@true402.dev/openclaw-swap-guard 1.0.1 → 1.0.3

package/README.md

@@ -28,13 +28,15 @@ It recognises buys in shell commands the way trading skills run them (`--token-o
 
 No setup is needed for a few checks a day: the guard uses true402's free daily allowance.
 
-For more, give it a **separate, low-balance** Base wallet holding a little USDC (gas is sponsored):
+For more, give it a **dedicated, low-balance** Base wallet holding a little USDC (gas is sponsored):
 
 ```bash
-export TRUE402_PAYER_PRIVATE_KEY=0x…   # or PAYER_PRIVATE_KEY
+export TRUE402_PAYER_PRIVATE_KEY=0x…
 ```
 
-Each check then pays the exact quoted price over [x402](https://x402.org) — no account, no API key. The key is read from the environment, never from OpenClaw's config file, and is never sent anywhere: it signs a USDC authorization locally. The guard **refuses to sign more than $0.25** for a single check.
+Only this dedicated variable is read — never a generic `PAYER_PRIVATE_KEY` another tool may have set. Each check then pays the exact quoted price over [x402](https://x402.org), no account and no API key. The key stays on your machine (it authorizes each USDC payment locally) and is never written to OpenClaw's config.
+
+Spending is bounded twice: **at most $0.02 per check** (`maxAmountUsd`) and **at most 50 paid checks per UTC day** (`maxPaidChecksPerDay`) — at most $1.00 a day by default. The day's count is kept in `$OPENCLAW_STATE_DIR/true402-swap-guard/spend.json` (default `~/.openclaw/…`), so restarting OpenClaw does not reset it; if that file cannot be written, no payment is made. Past the limit only free checks run, and the guard logs a warning. The limit is per machine: several OpenClaw installs with their own state directories each have their own.
 
 ## Settings
 
@@ -47,11 +49,14 @@ All optional, under the plugin's config (`true402-swap-guard`):
 | `onUnchecked` | `allow` | `ask` or `block` when a token could not be checked |
 | `allowTokens` | `[]` | Token addresses never checked |
 | `timeoutMs` | `15000` | Give up on a free check after this long (then it is "unchecked"). A paid check is never abandoned once paid — you get the answer you paid for |
-| `maxAmountUsd` | `0.25` | Never sign a single check payment above this |
+| `maxAmountUsd` | `0.02` | Never pay more than this for one check |
+| `maxPaidChecksPerDay` | `50` | Paid checks per UTC day; after that only free checks run |
 
 ## What is sent
 
-Only the token address and its chain, to `true402.dev`. Nothing about your wallet, your prompts or the trade itself.
+A **free check** sends only the token address and its chain to `true402.dev` — nothing about your wallet, your prompts or the trade.
+
+A **paid check** also sends a signed USDC payment authorization. That necessarily reveals the paying wallet's **address** to true402, and the payment is settled on Base, where it is public. That is why the wallet should be a dedicated, low-balance one. The private key itself never leaves your machine.
 
 ## License
 

package/dist/index.js

@@ -267,6 +267,11 @@ function clean(s, max = 160) {
   return t.length > max ? `${t.slice(0, max - 1)}\u2026` : t;
 }
 
+// src/check.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
 // src/x402.ts
 import { randomBytes } from "crypto";
 import { createPublicClient, http, getAddress } from "viem";
@@ -274,7 +279,7 @@ import { privateKeyToAccount } from "viem/accounts";
 import { base } from "viem/chains";
 
 // src/client.ts
-var CLIENT = { id: "openclaw-guard", version: "1.0.1", package: "@true402.dev/openclaw-swap-guard", install: "openclaw plugins install @true402.dev/openclaw-swap-guard" };
+var CLIENT = { id: "openclaw-guard", version: "1.0.3", package: "@true402.dev/openclaw-swap-guard", install: "openclaw plugins install @true402.dev/openclaw-swap-guard" };
 
 // src/x402.ts
 var USDC_ABI = [
@@ -447,6 +452,24 @@ async function payStall(path, payload, opts) {
 }
 
 // src/check.ts
+function fileSpendStore(path = join(process.env.OPENCLAW_STATE_DIR || join(homedir(), ".openclaw"), "true402-swap-guard", "spend.json")) {
+  return {
+    read() {
+      try {
+        const v = JSON.parse(readFileSync(path, "utf8"));
+        return { day: typeof v.day === "string" ? v.day : "", count: typeof v.count === "number" && v.count >= 0 ? v.count : 0 };
+      } catch {
+        return { day: "", count: 0 };
+      }
+    },
+    write(v) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(v), { mode: 384 });
+    }
+  };
+}
+var DEFAULT_MAX_PER_CHECK_USD = 0.02;
+var DEFAULT_MAX_PAID_CHECKS_PER_DAY = 50;
 var NOT_A_TOKEN = /* @__PURE__ */ new Set(["not_a_contract", "mint_unreadable", "mint_not_initialized"]);
 var SOL_NEVER_SELLABLE = /* @__PURE__ */ new Set(["non_transferable", "permanent_delegate"]);
 var SOL_SELL_BLOCKABLE = /* @__PURE__ */ new Set(["freeze_authority_active", "pausable", "transfer_hook", "default_frozen"]);
@@ -490,6 +513,10 @@ function strings(v) {
 function createChecker(cfg = {}) {
   const baseUrl = cfg.baseUrl ?? "https://true402.dev/api";
   const timeoutMs = cfg.timeoutMs ?? 15e3;
+  const perCheck = cfg.maxAmountUsd ?? DEFAULT_MAX_PER_CHECK_USD;
+  const perDay = cfg.maxPaidChecksPerDay ?? DEFAULT_MAX_PAID_CHECKS_PER_DAY;
+  const now = cfg.now ?? Date.now;
+  const store = cfg.spendStore ?? fileSpendStore();
   async function free(path, token) {
     const res = await fetch(`${baseUrl}${path}`, {
       method: "POST",
@@ -507,8 +534,17 @@ function createChecker(cfg = {}) {
     const toVerdict = (body2) => t.chain === "solana" ? solanaVerdict(body2) : evmVerdict(body2, t.chain);
     const body = await free(path, t.token);
     if (body !== null) return toVerdict(body);
-    if (!cfg.payerPrivateKey) throw new Error("the free daily checks are used up \u2014 set PAYER_PRIVATE_KEY to pay per check");
-    return toVerdict(await payStall(path, { token: t.token }, { payerPrivateKey: cfg.payerPrivateKey, baseUrl, maxAmountUsd: cfg.maxAmountUsd }));
+    if (!cfg.payerPrivateKey) throw new Error("the free daily checks are used up \u2014 set TRUE402_PAYER_PRIVATE_KEY to pay per check");
+    const today = new Date(now()).toISOString().slice(0, 10);
+    const saved = store.read();
+    const paidToday = saved.day === today ? saved.count : 0;
+    if (paidToday >= perDay) throw new Error(`the daily limit of ${perDay} paid checks is reached (maxPaidChecksPerDay)`);
+    try {
+      store.write({ day: today, count: paidToday + 1 });
+    } catch {
+      throw new Error("could not record the paid-check count, so no payment was made");
+    }
+    return toVerdict(await payStall(path, { token: t.token }, { payerPrivateKey: cfg.payerPrivateKey, baseUrl, maxAmountUsd: perCheck }));
   };
 }
 
@@ -524,7 +560,8 @@ function readConfig(raw) {
     onUnchecked: pick(c.onUnchecked, ["allow", "ask", "block"]),
     allowTokens: Array.isArray(c.allowTokens) ? c.allowTokens.filter((x) => typeof x === "string") : void 0,
     timeoutMs: num(c.timeoutMs),
-    maxAmountUsd: num(c.maxAmountUsd)
+    maxAmountUsd: num(c.maxAmountUsd),
+    maxPaidChecksPerDay: num(c.maxPaidChecksPerDay)
   };
 }
 var index_default = definePluginEntry({
@@ -533,7 +570,7 @@ var index_default = definePluginEntry({
   description: "Blocks token buys when true402 finds a honeypot or a rug in progress (Base, Ethereum, BSC, Solana).",
   register(api) {
     const cfg = readConfig(api.pluginConfig);
-    const payerPrivateKey = process.env.TRUE402_PAYER_PRIVATE_KEY || process.env.PAYER_PRIVATE_KEY || void 0;
+    const payerPrivateKey = process.env.TRUE402_PAYER_PRIVATE_KEY || void 0;
     const warn = (m) => api.logger?.warn ? api.logger.warn(m) : console.warn(m);
     const guard = createGuard(createChecker({ ...cfg, payerPrivateKey }), { ...cfg, warn });
     api.on("before_tool_call", (event, ctx) => guard(event.toolName, event.params ?? {}, ctx?.abortSignal), { priority: 60 });

package/openclaw.plugin.json

@@ -15,7 +15,8 @@
       "onUnchecked": { "type": "string", "enum": ["allow", "ask", "block"], "description": "When a token could not be checked (API unreachable, free checks used up): allow (default), ask, or block." },
       "allowTokens": { "type": "array", "items": { "type": "string" }, "description": "Token addresses never checked." },
       "timeoutMs": { "type": "number", "description": "Give up on one check after this many ms (default 15000)." },
-      "maxAmountUsd": { "type": "number", "description": "Never sign a single check payment above this, in USDC (default 0.25)." }
+      "maxAmountUsd": { "type": "number", "description": "Never pay more than this for one check, in USDC (default 0.02)." },
+      "maxPaidChecksPerDay": { "type": "number", "description": "At most this many paid checks per day; beyond it only free checks run (default 50)." }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@true402.dev/openclaw-swap-guard",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "OpenClaw plugin: before any tool call that buys a token, check it with true402 (executed buy/sell honeypot simulation) and block honeypots and rugs. Base, Ethereum, BSC, Solana. Free daily checks; pay-per-check over x402.",
   "type": "module",
   "main": "dist/index.js",