@true402.dev/openclaw-swap-guard 1.0.0 → 1.0.2

package/README.md

@@ -19,7 +19,7 @@ Before a tool call that buys a token, the guard asks [true402](https://true402.d
 
 - **Blocks** only on a definite danger verdict: an EVM token rated *avoid* (cannot be sold, extreme sell tax, liquidity just pulled…), or a Solana mint that can never be sold, can be seized, or is critical risk. The agent sees the reasons and is told not to retry with another tool.
 - **Lets the trade through** when the token checks out — and, by default, when it could not be checked at all (true402 unreachable, free checks used up, the address is a wallet rather than a token). A guard that breaks your trading whenever a third party hiccups is a guard you uninstall. Change that with `onUnchecked`.
-- Checks only the token being **bought**. The token you are selling is never checked: blocking the exit from a token whose liquidity is being pulled would trap you in it.
+- Never blocks a **sale**. The token you are selling is not checked, and when a command is ambiguous enough that a dangerous token *might* be the one being sold, the guard asks you instead of blocking — trapping you in a token whose liquidity is being pulled would be worse than the trade.
 - Skips majors and stablecoins (WETH, USDC, USDT, DAI, WBNB, SOL…), reuses a verdict for 10 minutes, and checks up to 5 distinct tokens per call — a call naming more is held for your approval (or blocked with `onUnchecked: block`). A token on a chain true402 does not serve counts as "could not be checked".
 
 It recognises buys in shell commands the way trading skills run them (`--token-out 0x…`, `trade <amount> <from> <to>`, `<script> <CA> --chain base`, `--chain solana <mint>`) and in structured tool parameters (`tokenOut`, `outputMint`, `token`, …). Command parsing fails closed: a token is checked on the default chain and on every chain the command names, and anything ambiguous — a `#`, `$'…'`, unbalanced quotes — means every address is checked, including the one being sold. A plain-English order that names no address (`"buy $20 of PEPE"`), or a token passed through a shell variable, cannot be checked.
@@ -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 a day** (`maxPaidChecksPerDay`) — so never more than $1.00 a day by default. Past the daily limit, only free checks run, and the guard logs a warning.
 
 ## Settings
 
@@ -46,8 +48,9 @@ All optional, under the plugin's config (`true402-swap-guard`):
 | `onCaution` | `allow` | `ask` = request your approval on a *caution* verdict |
 | `onUnchecked` | `allow` | `ask` or `block` when a token could not be checked |
 | `allowTokens` | `[]` | Token addresses never checked |
-| `timeoutMs` | `15000` | Give up on one check after this long (then it is "unchecked") |
-| `maxAmountUsd` | `0.25` | Never sign a single check payment above this |
+| `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.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
 

package/dist/index.js

@@ -101,6 +101,11 @@ function fromCommand(cmd, defaultChain) {
   const evmChains = [.../* @__PURE__ */ new Set([...[...supported].filter((c) => c !== "solana"), defaultChain])];
   const unambiguous = !/#|\$'/.test(cmd) && (cmd.match(/"/g) ?? []).length % 2 === 0 && (cmd.match(/'/g) ?? []).length % 2 === 0;
   const sold = /* @__PURE__ */ new Map();
+  const soldAny = new Set(flags(cmd, IN_FLAGS).map((v) => v.toLowerCase()));
+  for (const seg of cmd.split(/;|&&?|\|\|?|\n/)) {
+    const p = /\bawal\b/.test(seg) ? seg.match(/\btrade\s+(\S+)\s+(\S+)\s+(\S+)/) : null;
+    if (p) soldAny.add(p[2].replace(/['"]/g, "").toLowerCase());
+  }
   if (unambiguous) {
     const markSold = (v) => sold.set(v.toLowerCase(), (sold.get(v.toLowerCase()) ?? 0) + 1);
     for (const v of flags(cmd, IN_FLAGS)) markSold(v);
@@ -112,14 +117,17 @@ function fromCommand(cmd, defaultChain) {
   const mentions = (v) => cmd.toLowerCase().split(v.toLowerCase()).length - 1;
   const keep = (v) => !skip(v) && (sold.get(v.toLowerCase()) ?? 0) < mentions(v);
   const out = [];
+  const boughtByFlag = new Set(flags(cmd, OUT_FLAGS).map((v) => v.toLowerCase()));
+  const maybeSold = (tok) => !unambiguous && soldAny.has(tok.toLowerCase()) && !boughtByFlag.has(tok.toLowerCase());
+  const push = (t) => out.push(maybeSold(t.token) ? { ...t, maybeSold: true } : t);
   const evm = [...new Set([...cmd.matchAll(EVM_ADDRESS)].map((m) => m[0]))].filter(keep);
-  for (const chain of evmChains) for (const a of evm) out.push({ chain, token: a });
-  if (unsupportedNamed) for (const a of evm) out.push({ chain: "unsupported", token: a });
+  for (const chain of evmChains) for (const a of evm) push({ chain, token: a });
+  if (unsupportedNamed) for (const a of evm) push({ chain: "unsupported", token: a });
   const words = [...new Set(cmd.split(/[\s;|&`()]+/).map((x) => x.replace(/^[^=]*=/, "").replace(/['"]/g, "")))];
   if (supported.has("solana")) {
-    for (const w of words) if (SOLANA_MINT.test(w) && keep(w)) out.push({ chain: "solana", token: w });
+    for (const w of words) if (SOLANA_MINT.test(w) && keep(w)) push({ chain: "solana", token: w });
   } else if (!supported.size) {
-    for (const v of flags(cmd, OUT_FLAGS)) if (SOLANA_MINT.test(v) && !isEvm(v) && keep(v)) out.push({ chain: "solana", token: v });
+    for (const v of flags(cmd, OUT_FLAGS)) if (SOLANA_MINT.test(v) && !isEvm(v) && keep(v)) push({ chain: "solana", token: v });
   }
   return out;
 }
@@ -220,29 +228,33 @@ function createGuard(check, cfg = {}, now = Date.now) {
         return { t: ts[0], v: { level: "unchecked", reasons: [...new Set(vs.flatMap((x) => x.reasons))] } };
       })
     );
-    const danger = results.find((r) => r.v.level === "danger");
+    const danger = results.find((r) => r.v.level === "danger" && !r.t.maybeSold);
     if (danger) {
       return {
         block: true,
         blockReason: `true402 swap guard blocked this trade: ${danger.t.token} on ${danger.t.chain} was rated dangerous${reasonText(danger.v)}. Do not retry it with another tool. To trade it anyway, add the address to the plugin's allowTokens setting.`
       };
     }
+    const unchecked = results.find((r) => r.v.level === "unchecked");
+    if (unchecked) warnOnce(unchecked.v.reasons[0] ?? "unknown");
+    const uncheckedWhy = unchecked && `true402 could not check ${unchecked.t.token} on ${unchecked.t.chain}${reasonText(unchecked.v)}.`;
+    if (unchecked && cfg.onUnchecked === "block") return { block: true, blockReason: `true402 swap guard blocked this trade: ${uncheckedWhy}` };
+    const asks = [];
+    let severity = "info";
+    const dangerSold = results.find((r) => r.v.level === "danger" && r.t.maybeSold);
+    if (dangerSold) {
+      asks.push(`true402 rated ${dangerSold.t.token} on ${dangerSold.t.chain} dangerous${reasonText(dangerSold.v)}. If you are selling it, approve; if this buys it, deny.`);
+      severity = "critical";
+    }
     const caution = results.find((r) => r.v.level === "caution");
     if (caution && cfg.onCaution === "ask") {
-      return {
-        requireApproval: {
-          title: "Risky token \u2014 confirm the trade",
-          description: `true402 rated ${caution.t.token} on ${caution.t.chain} "caution"${reasonText(caution.v)}.`,
-          severity: "warning"
-        }
-      };
+      asks.push(`true402 rated ${caution.t.token} on ${caution.t.chain} "caution"${reasonText(caution.v)}.`);
+      if (severity !== "critical") severity = "warning";
     }
-    const unchecked = results.find((r) => r.v.level === "unchecked");
-    if (unchecked) warnOnce(unchecked.v.reasons[0] ?? "unknown");
-    if (unchecked && cfg.onUnchecked && cfg.onUnchecked !== "allow") {
-      const why = `true402 could not check ${unchecked.t.token} on ${unchecked.t.chain}${reasonText(unchecked.v)}.`;
-      if (cfg.onUnchecked === "block") return { block: true, blockReason: `true402 swap guard blocked this trade: ${why}` };
-      return { requireApproval: { title: "Unchecked token \u2014 confirm the trade", description: why, severity: "info" } };
+    if (unchecked && cfg.onUnchecked === "ask") asks.push(uncheckedWhy);
+    if (asks.length) {
+      const title = dangerSold ? "Dangerous token \u2014 confirm the trade" : caution && cfg.onCaution === "ask" ? "Risky token \u2014 confirm the trade" : "Unchecked token \u2014 confirm the trade";
+      return { requireApproval: { title, description: asks.join(" "), severity } };
     }
     return void 0;
   };
@@ -262,7 +274,7 @@ import { privateKeyToAccount } from "viem/accounts";
 import { base } from "viem/chains";
 
 // src/client.ts
-var CLIENT = { id: "openclaw-guard", version: "1.0.0", package: "@true402.dev/openclaw-swap-guard", install: "openclaw plugins install @true402.dev/openclaw-swap-guard" };
+var CLIENT = { id: "openclaw-guard", version: "1.0.2", package: "@true402.dev/openclaw-swap-guard", install: "openclaw plugins install @true402.dev/openclaw-swap-guard" };
 
 // src/x402.ts
 var USDC_ABI = [
@@ -435,6 +447,8 @@ async function payStall(path, payload, opts) {
 }
 
 // src/check.ts
+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"]);
@@ -478,10 +492,12 @@ function strings(v) {
 function createChecker(cfg = {}) {
   const baseUrl = cfg.baseUrl ?? "https://true402.dev/api";
   const timeoutMs = cfg.timeoutMs ?? 15e3;
-  async function ask(path, token) {
-    if (cfg.payerPrivateKey) {
-      return payStall(path, { token }, { payerPrivateKey: cfg.payerPrivateKey, baseUrl, maxAmountUsd: cfg.maxAmountUsd });
-    }
+  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;
+  let day = "";
+  let paidToday = 0;
+  async function free(path, token) {
     const res = await fetch(`${baseUrl}${path}`, {
       method: "POST",
       headers: { "content-type": "application/json", "user-agent": `true402-${CLIENT.id}/${CLIENT.version} (+https://true402.dev)` },
@@ -489,22 +505,21 @@ function createChecker(cfg = {}) {
       redirect: "manual",
       signal: AbortSignal.timeout(timeoutMs)
     });
-    if (res.status === 402) throw new Error("the free daily checks are used up \u2014 set PAYER_PRIVATE_KEY to pay per check");
+    if (res.status === 402) return null;
     if (!res.ok) throw new Error(`true402 answered HTTP ${res.status}`);
     return res.json();
   }
   return async (t) => {
     const path = t.chain === "solana" ? "/v1/solana/token-safety" : `/v1/${t.chain}/token-report`;
-    let timer;
-    const deadline = new Promise((_, reject) => {
-      timer = setTimeout(() => reject(new Error(`no answer within ${timeoutMs} ms`)), timeoutMs);
-    });
-    try {
-      const body = await Promise.race([ask(path, t.token), deadline]);
-      return t.chain === "solana" ? solanaVerdict(body) : evmVerdict(body, t.chain);
-    } finally {
-      clearTimeout(timer);
-    }
+    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 TRUE402_PAYER_PRIVATE_KEY to pay per check");
+    const today = new Date(now()).toISOString().slice(0, 10);
+    if (today !== day) [day, paidToday] = [today, 0];
+    if (paidToday >= perDay) throw new Error(`the daily limit of ${perDay} paid checks is reached (maxPaidChecksPerDay)`);
+    paidToday++;
+    return toVerdict(await payStall(path, { token: t.token }, { payerPrivateKey: cfg.payerPrivateKey, baseUrl, maxAmountUsd: perCheck }));
   };
 }
 
@@ -520,7 +535,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({
@@ -529,7 +545,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.0",
+  "version": "1.0.2",
   "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",
@@ -29,7 +29,7 @@
   "homepage": "https://true402.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/true402/openclaw-swap-guard"
+    "url": "git+https://github.com/true402/openclaw-swap-guard.git"
   },
   "license": "MIT",
   "dependencies": {