@true402.dev/openclaw-swap-guard 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 true402
+
+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

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @true402.dev/openclaw-swap-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**An OpenClaw plugin that checks every token your agent is about to buy, and blocks the trade when the token is a honeypot or a rug in progress.**
+
+It hooks OpenClaw's `before_tool_call`, so it sits in front of *every* trading skill and MCP tool you have installed — Base trade skills, Uniswap, Jupiter, sniper bots, your own scripts. A skill the agent forgets to follow cannot skip it.
+
+```bash
+openclaw plugins install @true402.dev/openclaw-swap-guard
+```
+
+## What it does
+
+Before a tool call that buys a token, the guard asks [true402](https://true402.dev):
+
+| Chain | Check | Price after the free daily checks |
+|---|---|---|
+| Base, Ethereum, BSC | `/v1/{chain}/token-report`: an executed buy **and sell** simulation, deployer history, recent liquidity pulls | $0.008 |
+| Solana | `/v1/solana/token-safety`: freeze / mint authority, Token-2022 extensions, liquidity | $0.005 |
+
+- **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.
+- 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.
+
+## Paying for checks
+
+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):
+
+```bash
+export TRUE402_PAYER_PRIVATE_KEY=0x…   # or PAYER_PRIVATE_KEY
+```
+
+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.
+
+## Settings
+
+All optional, under the plugin's config (`true402-swap-guard`):
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `defaultChain` | `base` | Chain assumed for a `0x` address when the trade names none (`base`, `ethereum`, `bsc`) |
+| `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 |
+
+## What is sent
+
+Only the token address and its chain, to `true402.dev`. Nothing about your wallet, your prompts or the trade itself.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,541 @@
+// src/index.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+
+// src/detect.ts
+var EVM_ADDRESS = /0x[a-fA-F0-9]{40}\b/g;
+var SOLANA_MINT = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+var TRADE_VERB = /\b(swap|swaps|buy|buys|trade|snipe|ape|purchase|enter|market-buy|limit-buy)\b|tradr-enter|--token-out|--output-mint|--buy-token/i;
+var TRADE_TOOL = /(swap|buy|trade|snipe|purchase|order)/i;
+var OUT_KEYS = ["tokenout", "token_out", "outputmint", "output_mint", "outputtoken", "output_token", "totoken", "to_token", "buytoken", "buy_token", "tokentobuy", "mintout", "outmint", "to"];
+var TOKEN_KEYS = ["token", "tokenaddress", "token_address", "mint", "ca", "contract", "contractaddress", "contract_address", "address", "asset"];
+var PARTY_KEYS = /recipient|receiver|wallet|owner|sender|spender|from_address|payer|beneficiary|account|user/i;
+var SKIP = /* @__PURE__ */ new Set(
+  [
+    "0x0000000000000000000000000000000000000000",
+    "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+    // native-asset sentinel
+    "0x4200000000000000000000000000000000000006",
+    // WETH (Base)
+    "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    // USDC (Base)
+    "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
+    // WETH (Ethereum)
+    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+    // USDC (Ethereum)
+    "0xdac17f958d2ee523a2206206994597c13d831ec7",
+    // USDT (Ethereum)
+    "0x6b175474e89094c44da98b954eedeac495271d0f",
+    // DAI (Ethereum)
+    "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
+    // WBNB
+    "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
+    // USDC (BSC)
+    "0x55d398326f99059ff775485246999027b3197955",
+    // USDT (BSC)
+    "so11111111111111111111111111111111111111112",
+    // wrapped SOL
+    "epjfwdd5aufqssqem2qn1xzybapc8g4wegggkzwytdt1v",
+    // USDC (Solana)
+    "es9vmfrzacermjfrf4h2fyd4kconky11mcce8benwnyb"
+    // USDT (Solana)
+  ]
+);
+var CHAIN_NAMES = {
+  base: "base",
+  "8453": "base",
+  "eip155:8453": "base",
+  ethereum: "ethereum",
+  eth: "ethereum",
+  mainnet: "ethereum",
+  "1": "ethereum",
+  "eip155:1": "ethereum",
+  bsc: "bsc",
+  bnb: "bsc",
+  binance: "bsc",
+  "56": "bsc",
+  "eip155:56": "bsc",
+  solana: "solana",
+  sol: "solana"
+};
+function readChain(v) {
+  if (v === void 0 || v === null || v === "") return void 0;
+  const s = String(v).toLowerCase().trim();
+  return CHAIN_NAMES[s] ?? "unsupported";
+}
+function norm(k) {
+  return k.toLowerCase().replace(/-/g, "_").replace(/^_+/, "");
+}
+function skip(token) {
+  return SKIP.has(token.toLowerCase());
+}
+function isEvm(s) {
+  return /^0x[a-fA-F0-9]{40}$/.test(s);
+}
+var IN_FLAGS = ["token-in", "input-mint", "from-token", "sell-token", "from", "in"];
+var OUT_FLAGS = ["token-out", "output-mint", "to-token", "buy-token", "mint", "token", "ca"];
+function commandOf(params) {
+  for (const k of ["command", "cmd", "script", "input"]) if (typeof params[k] === "string") return params[k];
+  return void 0;
+}
+function flags(seg, names) {
+  const out = [];
+  for (const n of names) for (const m of seg.matchAll(new RegExp(`--${n}(?:=|\\s+)['"]?([^\\s'"]+)`, "gi"))) out.push(m[1]);
+  return out;
+}
+function detectTrade(toolName, params, defaultChain = "base") {
+  const found = [];
+  const cmd = commandOf(params);
+  if (cmd !== void 0) found.push(...fromCommand(cmd, defaultChain));
+  if (TRADE_TOOL.test(toolName)) found.push(...fromParams(params, defaultChain));
+  const seen = /* @__PURE__ */ new Set();
+  return found.filter((t) => {
+    const k = `${t.chain}:${t.token.toLowerCase()}`;
+    return seen.has(k) ? false : (seen.add(k), true);
+  });
+}
+function fromCommand(cmd, defaultChain) {
+  if (!TRADE_VERB.test(cmd)) return [];
+  const named = flags(cmd, ["chain", "network"]).map((v) => readChain(v));
+  const supported = new Set(named.filter((c) => c !== void 0 && c !== "unsupported"));
+  const unsupportedNamed = named.includes("unsupported");
+  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();
+  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);
+    for (const seg of cmd.split(/;|&&?|\|\|?|\n/)) {
+      const positional = /\bawal\b/.test(seg) ? seg.match(/\btrade\s+(\S+)\s+(\S+)\s+(\S+)/) : null;
+      if (positional) markSold(positional[2].replace(/['"]/g, ""));
+    }
+  }
+  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 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 });
+  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 });
+  } 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 });
+  }
+  return out;
+}
+function fromParams(params, defaultChain) {
+  const flat = flatten(params);
+  const chain = readChain(flat.get("chain") ?? flat.get("network") ?? flat.get("chainid") ?? flat.get("chain_id"));
+  for (const keys of [OUT_KEYS, TOKEN_KEYS]) {
+    for (const k of keys) {
+      const v = flat.get(k);
+      if (typeof v === "string") {
+        const t = target(v, chain, defaultChain, true);
+        if (t.length) return t;
+      }
+    }
+  }
+  return [];
+}
+function flatten(params) {
+  const m = /* @__PURE__ */ new Map();
+  const add = (k, v) => {
+    const n = norm(k);
+    if (PARTY_KEYS.test(n)) return;
+    if (!m.has(n)) m.set(n, v);
+    const squashed = n.replace(/_/g, "");
+    if (!m.has(squashed)) m.set(squashed, v);
+  };
+  for (const [k, v] of Object.entries(params)) {
+    if (v && typeof v === "object" && !Array.isArray(v)) for (const [k2, v2] of Object.entries(v)) add(k2, v2);
+    else add(k, v);
+  }
+  return m;
+}
+function target(raw, chain, defaultChain, named) {
+  const v = raw.trim();
+  if (skip(v)) return [];
+  if (isEvm(v)) return [{ chain: chain === "unsupported" ? "unsupported" : chain && chain !== "solana" ? chain : defaultChain, token: v }];
+  if (named && SOLANA_MINT.test(v) && (chain === void 0 || chain === "solana")) return [{ chain: "solana", token: v }];
+  return [];
+}
+
+// src/guard.ts
+var MAX_TOKENS = 5;
+function createGuard(check, cfg = {}, now = Date.now) {
+  const cacheMs = cfg.cacheMs ?? 10 * 6e4;
+  const allow = new Set((cfg.allowTokens ?? []).map((a) => a.toLowerCase()));
+  const cache = /* @__PURE__ */ new Map();
+  const warned = /* @__PURE__ */ new Map();
+  const warnOnce = (why) => {
+    if (!cfg.warn) return;
+    const last = warned.get(why);
+    if (last !== void 0 && now() - last < 10 * 6e4) return;
+    warned.set(why, now());
+    cfg.warn(`true402 swap guard: a token could not be checked (${why}); the trade was ${cfg.onUnchecked === "block" ? "blocked" : cfg.onUnchecked === "ask" ? "held for approval" : "allowed unchecked"}.`);
+  };
+  async function verdict(t, signal) {
+    const key = `${t.chain}:${t.token.toLowerCase()}`;
+    const hit = cache.get(key);
+    if (hit && now() - hit.at < cacheMs) return hit.v;
+    let v;
+    try {
+      v = await check(t, signal);
+    } catch (e) {
+      v = { level: "unchecked", reasons: [clean(e instanceof Error ? e.message : String(e))] };
+    }
+    if (v.level !== "unchecked") cache.set(key, { at: now(), v });
+    return v;
+  }
+  return async function beforeToolCall(toolName, params, signal) {
+    const targets = detectTrade(toolName, params, cfg.defaultChain ?? "base").filter((t) => !allow.has(t.token.toLowerCase()));
+    if (!targets.length) return void 0;
+    const byToken = /* @__PURE__ */ new Map();
+    for (const t of targets) {
+      const k = t.token.toLowerCase();
+      byToken.set(k, [...byToken.get(k) ?? [], t]);
+    }
+    const groups = [...byToken.values()];
+    if (groups.length > MAX_TOKENS) {
+      const why = `this call names ${groups.length} tokens; the guard checks at most ${MAX_TOKENS} per call`;
+      warnOnce(why);
+      if (cfg.onUnchecked === "block") return { block: true, blockReason: `true402 swap guard blocked this trade: ${why}.` };
+      return { requireApproval: { title: "Too many tokens to check \u2014 confirm the trade", description: `${why}.`, severity: "warning" } };
+    }
+    const results = await Promise.all(
+      groups.map(async (ts) => {
+        const vs = await Promise.all(
+          ts.map((t) => t.chain === "unsupported" ? Promise.resolve({ level: "unchecked", reasons: ["a chain true402 does not serve"] }) : verdict(t, signal))
+        );
+        const pick = (level) => vs.findIndex((x) => x.level === level);
+        if (pick("danger") >= 0) return { t: ts[pick("danger")], v: vs[pick("danger")] };
+        const u = ts.findIndex((t) => t.chain === "unsupported");
+        if (u >= 0) return { t: ts[u], v: vs[u] };
+        const failed = vs.findIndex((x) => x.level === "unchecked" && !x.notToken);
+        if (failed >= 0) return { t: ts[failed], v: vs[failed] };
+        for (const level of ["caution", "ok"]) {
+          const i = pick(level);
+          if (i >= 0) return { t: ts[i], v: vs[i] };
+        }
+        return { t: ts[0], v: { level: "unchecked", reasons: [...new Set(vs.flatMap((x) => x.reasons))] } };
+      })
+    );
+    const danger = results.find((r) => r.v.level === "danger");
+    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 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"
+        }
+      };
+    }
+    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" } };
+    }
+    return void 0;
+  };
+}
+function reasonText(v) {
+  return v.reasons.length ? ` (${v.reasons.slice(0, 4).join("; ")})` : "";
+}
+function clean(s, max = 160) {
+  const t = s.replace(/[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g, " ").replace(/\s+/g, " ").trim();
+  return t.length > max ? `${t.slice(0, max - 1)}\u2026` : t;
+}
+
+// src/x402.ts
+import { randomBytes } from "crypto";
+import { createPublicClient, http, getAddress } from "viem";
+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" };
+
+// src/x402.ts
+var USDC_ABI = [
+  { name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "a", type: "address" }], outputs: [{ type: "uint256" }] }
+];
+var BASE_USDC = getAddress("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+var BASE_NETWORK = "eip155:8453";
+var MIN_AUTH_WINDOW_S = 30;
+var MAX_AUTH_WINDOW_S = 600;
+var DEFAULT_AUTH_WINDOW_S = 120;
+function authWindowSeconds(raw) {
+  const n = typeof raw === "string" || typeof raw === "number" ? Number(raw) : NaN;
+  if (!Number.isInteger(n) || n <= 0) return DEFAULT_AUTH_WINDOW_S;
+  return Math.min(MAX_AUTH_WINDOW_S, Math.max(MIN_AUTH_WINDOW_S, n));
+}
+var USER_AGENT = `true402-${CLIENT.id}/${CLIENT.version} (+https://true402.dev/integrations)`;
+var updateNoticeShown = false;
+var DEFAULT_ORIGIN = "https://true402.dev/api";
+var isTrue402 = (url) => {
+  try {
+    const host = new URL(url).hostname;
+    return host === "true402.dev" || host.endsWith(".true402.dev");
+  } catch {
+    return false;
+  }
+};
+var isNewer = (a, b) => {
+  const x = a.split(".").map(Number);
+  const y = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+};
+function updateNotice(res, fromUrl = DEFAULT_ORIGIN) {
+  if (!isTrue402(fromUrl)) return null;
+  let latest = "";
+  let required = false;
+  try {
+    latest = res.headers.get("x-true402-client-latest")?.trim() ?? "";
+    required = res.headers.get("x-true402-client-update") === "required";
+  } catch {
+    return null;
+  }
+  if (!/^\d{1,4}\.\d{1,4}\.\d{1,4}$/.test(latest) || !isNewer(latest, CLIENT.version)) return null;
+  return required ? `[true402] ${CLIENT.package} ${CLIENT.version} has a security fix pending \u2014 update to ${latest}: ${CLIENT.install}` : `[true402] ${CLIENT.package} ${latest} is available (you have ${CLIENT.version}): ${CLIENT.install}`;
+}
+function noteUpdate(res, fromUrl) {
+  if (updateNoticeShown) return;
+  const line = updateNotice(res, fromUrl);
+  if (!line) return;
+  updateNoticeShown = true;
+  console.warn(line);
+}
+var PROBE_TIMEOUT_MS = 3e4;
+var PAID_TIMEOUT_MS = 12e4;
+async function serverReason(res) {
+  try {
+    const text = (await res.text()).trim();
+    return text ? ` \u2014 ${text.slice(0, 300)}` : "";
+  } catch {
+    return "";
+  }
+}
+function isSecureUrl(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  if (u.protocol === "https:") return true;
+  return u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+}
+function refuseRedirect(res, url) {
+  if (String(res.type) === "opaqueredirect" || res.status >= 300 && res.status < 400)
+    throw new Error(`${url} answered HTTP ${res.status}: server redirected; refusing to send a payment elsewhere`);
+}
+async function payStall(path, payload, opts) {
+  const baseUrl = opts.baseUrl ?? "https://true402.dev/api";
+  const rpcUrl = opts.rpcUrl ?? "https://mainnet.base.org";
+  const key = opts.payerPrivateKey.startsWith("0x") ? opts.payerPrivateKey : `0x${opts.payerPrivateKey}`;
+  const account = privateKeyToAccount(key);
+  const url = `${baseUrl}${path}`;
+  const body = JSON.stringify(payload);
+  const first = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", "user-agent": USER_AGENT },
+    body,
+    redirect: "manual",
+    signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+  });
+  noteUpdate(first, url);
+  refuseRedirect(first, url);
+  if (first.ok) return await first.json();
+  if (first.status !== 402)
+    throw new Error(`expected HTTP 402 from ${path}, got ${first.status}${await serverReason(first)}`);
+  const challenge = await first.json();
+  const req = (challenge.accepts ?? []).find((a) => a.scheme === "exact" && a.network === BASE_NETWORK);
+  if (!req)
+    throw new Error(
+      `no payable x402 requirement in the 402 \u2014 this client settles USDC on ${BASE_NETWORK} only`
+    );
+  if (req.network !== BASE_NETWORK) throw new Error(`unexpected payment network "${req.network}" (expected ${BASE_NETWORK}) \u2014 refusing to sign`);
+  const usdc = getAddress(req.asset);
+  if (usdc !== BASE_USDC) throw new Error(`unexpected payment asset ${usdc} (expected Base USDC) \u2014 refusing to sign`);
+  const rawAmount = req.amount ?? req.maxAmountRequired;
+  if (rawAmount === void 0 || !/^\d+$/.test(String(rawAmount)) || BigInt(rawAmount) <= 0n)
+    throw new Error("402 carries no positive payment amount \u2014 refusing to sign");
+  const value = BigInt(rawAmount);
+  const capAtomic = BigInt(Math.round((opts.maxAmountUsd ?? 0.25) * 1e6));
+  if (value > capAtomic) throw new Error(`402 demands ${value} USDC base units, over the $${opts.maxAmountUsd ?? 0.25} cap (maxAmountUsd) \u2014 refusing to sign`);
+  const pub = createPublicClient({ chain: base, transport: http(rpcUrl) });
+  const held = await pub.readContract({ address: usdc, abi: USDC_ABI, functionName: "balanceOf", args: [account.address] }).catch(() => null);
+  if (held !== null && held < value) throw new Error(`payer ${account.address} holds ${held} < ${value} USDC base units \u2014 fund it`);
+  if (!isSecureUrl(url)) {
+    throw new Error(`refusing to send a signed payment over cleartext (${url}) \u2014 use https`);
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const authorization = {
+    from: account.address,
+    to: getAddress(req.payTo),
+    value,
+    validAfter: BigInt(now - 60),
+    validBefore: BigInt(now + authWindowSeconds(req.maxTimeoutSeconds)),
+    nonce: `0x${randomBytes(32).toString("hex")}`
+  };
+  const signature = await account.signTypedData({
+    domain: { name: req.extra?.name ?? "USD Coin", version: req.extra?.version ?? "2", chainId: base.id, verifyingContract: usdc },
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" }
+      ]
+    },
+    primaryType: "TransferWithAuthorization",
+    message: authorization
+  });
+  const xPayment = Buffer.from(JSON.stringify({
+    x402Version: 2,
+    accepted: req,
+    payload: {
+      signature,
+      authorization: {
+        from: authorization.from,
+        to: authorization.to,
+        value: value.toString(),
+        validAfter: authorization.validAfter.toString(),
+        validBefore: authorization.validBefore.toString(),
+        nonce: authorization.nonce
+      }
+    }
+  })).toString("base64");
+  const paid = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", "user-agent": USER_AGENT, "PAYMENT-SIGNATURE": xPayment },
+    body,
+    redirect: "manual",
+    signal: AbortSignal.timeout(PAID_TIMEOUT_MS)
+  });
+  noteUpdate(paid, url);
+  refuseRedirect(paid, url);
+  if (!paid.ok)
+    throw new Error(
+      `paid request to ${path} failed (HTTP ${paid.status}): the server reported failure \u2014 a seller following x402 settles only on a 2xx${await serverReason(paid)}`
+    );
+  return await paid.json();
+}
+
+// src/check.ts
+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"]);
+function evmVerdict(r, chain) {
+  const flags2 = strings(r.safety?.flags);
+  if (flags2.some((f) => NOT_A_TOKEN.has(f))) return { level: "unchecked", notToken: true, reasons: [`no token contract at this address on ${chain}`] };
+  const reasons = strings(r.verdict?.reasons).map((s) => clean(s));
+  switch (r.verdict?.rating) {
+    case "avoid":
+      return { level: "danger", reasons };
+    case "caution":
+      return { level: "caution", reasons };
+    case "ok":
+      return { level: "ok", reasons };
+    default:
+      return { level: "unchecked", reasons: ["no verdict in the answer"] };
+  }
+}
+function solanaVerdict(r) {
+  const flags2 = strings(r.flags);
+  if (flags2.some((f) => NOT_A_TOKEN.has(f))) return { level: "unchecked", notToken: true, reasons: ["not a token mint on solana"] };
+  const reasons = flags2.map((f) => clean(f.replace(/_/g, " ")));
+  if (flags2.some((f) => SOL_NEVER_SELLABLE.has(f))) return { level: "danger", reasons };
+  const canStopSell = flags2.some((f) => SOL_SELL_BLOCKABLE.has(f));
+  switch (r.risk) {
+    case "critical":
+      return { level: "danger", reasons };
+    case "high":
+      return { level: canStopSell ? "danger" : "caution", reasons };
+    case "medium":
+      return { level: canStopSell ? "caution" : "ok", reasons };
+    case "low":
+      return { level: canStopSell ? "caution" : "ok", reasons };
+    default:
+      return { level: "unchecked", reasons: ["no risk level in the answer"] };
+  }
+}
+function strings(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+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 res = await fetch(`${baseUrl}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "user-agent": `true402-${CLIENT.id}/${CLIENT.version} (+https://true402.dev)` },
+      body: JSON.stringify({ token }),
+      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.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);
+    }
+  };
+}
+
+// src/index.ts
+var CHAINS = /* @__PURE__ */ new Set(["base", "ethereum", "bsc"]);
+function readConfig(raw) {
+  const c = raw && typeof raw === "object" ? raw : {};
+  const pick = (v, allowed) => allowed.includes(v) ? v : void 0;
+  const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : void 0;
+  return {
+    defaultChain: CHAINS.has(c.defaultChain) ? c.defaultChain : void 0,
+    onCaution: pick(c.onCaution, ["allow", "ask"]),
+    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)
+  };
+}
+var index_default = definePluginEntry({
+  id: "true402-swap-guard",
+  name: "true402 swap guard",
+  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 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 });
+  }
+});
+export {
+  index_default as default,
+  readConfig
+};

package/openclaw.plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "true402-swap-guard",
+  "name": "true402 swap guard",
+  "description": "Blocks token buys when true402 finds a honeypot or a rug in progress (Base, Ethereum, BSC, Solana).",
+  "categories": ["security"],
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "defaultChain": { "type": "string", "enum": ["base", "ethereum", "bsc"], "description": "Chain assumed for a 0x address when the trade names none. Default base." },
+      "onCaution": { "type": "string", "enum": ["allow", "ask"], "description": "On a 'caution' verdict: let the trade through (default) or ask you first." },
+      "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)." }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@true402.dev/openclaw-swap-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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",
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --external openclaw",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "x402",
+    "honeypot",
+    "rug-check",
+    "token-safety",
+    "swap",
+    "trading-agent",
+    "base",
+    "solana",
+    "ai-agents"
+  ],
+  "homepage": "https://true402.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/true402/openclaw-swap-guard"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.10.5"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@true402.dev/openclaw-swap-guard",
+      "npmSpec": "@true402.dev/openclaw-swap-guard",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.10.5"
+    },
+    "compat": {
+      "pluginApi": ">=2026.10.5"
+    },
+    "build": {
+      "openclawVersion": "2026.10.5"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild": true
+  }
+}