fizzl-langchain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frits Zwager
+
+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,4 +1,88 @@
-# Temporary Holding Version
-
-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.
-If no other versions are published within 30 days, this package and version will be deleted.
+# fizzl-langchain
+
+Safety checks for [LangChain.js](https://js.langchain.com) and [LangGraph.js](https://langchain-ai.github.io/langgraphjs/) agents that pay. The JavaScript twin of the [official LangChain integration](https://docs.langchain.com/oss/python/integrations/tools) `fizzl` for Python.
+
+Five LangChain tools you pass to `createAgent`, `createReactAgent` or `model.bindTools`:
+
+| Tool | What the agent checks | Service | Price |
+|---|---|---|---|
+| `check_before_signing` | a transaction, token approval or signature **before signing it**: green / orange / red with reason codes (drainers, unlimited approvals to unknown spenders, look-alike tokens, Permit/Permit2/Seaport signatures that hand over tokens) | [presign-guard](https://presign-guard.fizzl.eu) | $0.01 |
+| `check_xrpl_transaction` | an **XRP Ledger** transaction before signing it: account takeover (SetRegularKey, SignerListSet, master key off), AccountDelete, fake RLUSD (red); partial payments, destinations that refuse or need a tag, risky issuers, DEX orders far below the order book or AMM price (orange) | presign-guard | $0.01 |
+| `check_token` | a token **before buying or accepting it**: honeypot, rug-pull signs, look-alikes (Solana, EVM, and XRPL tokens as `CURRENCY.rIssuer`: clawback, freeze, transfer fee, fake RLUSD) | presign-guard | $0.01 |
+| `check_wallet_approvals` | every open approval of a wallet and which to revoke | presign-guard | $0.02 |
+| `check_endpoint_before_paying` | an x402 or MPP paid API **before paying it**: go / caution / no_go, the cheapest option that settles, budget, track record, bait signs (fake brands, airdrop lures, output that doesn't match) | [x402 Doctor](https://x402-doctor.fizzl.eu) | $0.001 |
+
+The tools only check. They never sign, pay or move anything themselves. A failed check comes back to the model as `{ "error", "message" }`, so the agent can tell the user instead of crashing. Each tool returns its answer as a JSON string.
+
+## Install
+
+```sh
+npm install fizzl-langchain @langchain/core zod
+npm install @x402/fetch @x402/evm viem   # to pay for the full checks over x402
+```
+
+## Try it without a wallet
+
+```js
+import { fizzlTools } from "fizzl-langchain";
+
+const [checkToken] = fizzlTools({ only: ["check_token"] });
+console.log(await checkToken.invoke({ chain: "base", address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }));
+// {"verdict":"green","grade":"SAFE","free":true,"note":"Free quick check: the verdict only, a few per hour. ..."}
+```
+
+With no paying fetch and no credit keys, `check_token`, `check_before_signing` and `check_endpoint_before_paying` fall back to the free quick checks: the verdict only (green / orange / red, or go / caution / no_go with the problems found), a few per hour, marked `free: true` with a note on what the full check costs. `check_wallet_approvals` and `check_xrpl_transaction` have no free version. Pass `free: false` to get `payment_required` instead.
+
+## Use in an agent
+
+```js
+import { createAgent } from "langchain";
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+import { fizzlTools } from "fizzl-langchain";
+
+// Pays for the checks over x402 (USDC on Base). Cap it: a check never costs more than $0.02.
+const payer = new x402Client().setSpendControls({ maxAmountPerPayment: "$0.02" });
+payer.register("eip155:8453", new ExactEvmScheme(privateKeyToAccount(process.env.AGENT_KEY)));
+const pay = wrapFetchWithPayment(fetch, payer);
+
+const agent = createAgent({
+  model: yourChatModel, // any chat model with tool calling
+  tools: [...fizzlTools({ fetch: pay }), ...yourOtherTools],
+  systemPrompt: "Before you pay any API, call check_endpoint_before_paying. Before you sign anything, call check_before_signing. Never continue on red or no_go.",
+});
+
+const result = await agent.invoke({ messages: [{ role: "user", content: "Buy the BTC funding rate from https://api.example.com/funding for at most $0.05" }] });
+```
+
+With LangGraph: `createReactAgent({ llm, tools: fizzlTools({ fetch: pay }) })` from `@langchain/langgraph/prebuilt`.
+
+**Prepaid credits instead of a payment per check:** buy a pack once ([presign-guard](https://presign-guard.fizzl.eu/v1/credits): 100 checks for $0.80; [x402 Doctor](https://x402-doctor.fizzl.eu/api/v1/credits): 1000 preflights for $0.80), then pass the keys and a plain `fetch`:
+
+```js
+fizzlTools({ creditKeys: { presign: process.env.PRESIGN_CREDIT_KEY, doctor: process.env.DOCTOR_CREDIT_KEY } });
+```
+
+**Only some tools:** `fizzlTools({ fetch: pay, only: ["check_endpoint_before_paying", "check_before_signing"] })`.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `fetch` | global `fetch` | An x402-paying fetch (`wrapFetchWithPayment` from `@x402/fetch`), or plain fetch with credit keys |
+| `creditKeys` | none | `{ presign, doctor }`, sent as `x-credit-key` |
+| `only` | all five | Tool names to include |
+| `free` | `true` | Fall back to the free quick check (verdict only) when a check can't be paid |
+| `timeoutMs` | 30000 | Per check |
+| `presignUrl`, `doctorUrl` | the fizzl.eu services | For tests or self-hosting |
+
+Works with `@langchain/core` 0.3.58+ and 1.x, zod 3.25+ or 4. The checks themselves come from [presign-guard-ai-sdk](https://www.npmjs.com/package/presign-guard-ai-sdk), the same tools for the Vercel AI SDK.
+
+## Want the agent to stop itself, not just be told?
+
+The tools inform the model; a model can still ignore them. To make red and over-budget payments impossible, guard the wallet itself with [presign-guard-wallet](https://www.npmjs.com/package/presign-guard-wallet): every signature then goes through presign-guard and your spending limits, with Telegram approval above them. Both together: the agent knows why, and the wallet enforces it.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,25 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+export declare const VERSION: string;
+export declare const PRESIGN_URL: string;
+export declare const DOCTOR_URL: string;
+export declare const PRICES: Record<FizzlToolName, string>;
+
+export type FizzlToolName = "check_before_signing" | "check_xrpl_transaction" | "check_token" | "check_wallet_approvals" | "check_endpoint_before_paying";
+
+export interface FizzlToolsOptions {
+  /** fetch that pays x402 (wrapFetchWithPayment from @x402/fetch); plain fetch works with credit keys. */
+  fetch?: typeof fetch;
+  /** Prepaid credit keys (sent as x-credit-key), per service. */
+  creditKeys?: { presign?: string; doctor?: string };
+  /** The tools to include (default: all five). */
+  only?: FizzlToolName[];
+  /** Fall back to the free quick check (verdict only, a few per hour) when a check can't be paid. Default true. */
+  free?: boolean;
+  presignUrl?: string;
+  doctorUrl?: string;
+  timeoutMs?: number;
+}
+
+/** LangChain tools; each returns the check's answer as a JSON string (or `{ "error", "message" }`). */
+export declare function fizzlTools(options?: FizzlToolsOptions): StructuredToolInterface[];

package/index.js

@@ -0,0 +1,35 @@
+// Fizzl safety checks as LangChain.js tools, for LangChain and LangGraph agents: check a transaction or
+// signature before signing, a token before buying, a wallet's open approvals, and an x402 endpoint before
+// paying it. Each tool calls a paid Fizzl API (presign-guard or x402 Doctor) through the fetch you pass: an
+// x402-paying fetch (@x402/fetch) or prepaid credit keys. Without either, the free quick check answers
+// (the verdict only, a few per hour).
+//
+// The tools only check; they never sign, pay or move anything themselves. A failed check comes back to the
+// model as { error, message }, never as an exception that ends the run.
+import { tool } from "@langchain/core/tools";
+import { fizzlTools as checks, PRICES, PRESIGN_URL, DOCTOR_URL } from "presign-guard-ai-sdk";
+
+export const VERSION = "0.1.0";
+export { PRICES, PRESIGN_URL, DOCTOR_URL };
+
+// The same checks as presign-guard-ai-sdk; only the user agent says where the call came from.
+function withUserAgent(fetchImpl) {
+  return (url, init = {}) => fetchImpl(url, { ...init, headers: { ...init.headers, "user-agent": `fizzl-langchain/${VERSION}` } });
+}
+
+/**
+ * The Fizzl checks as LangChain tools: pass them to createAgent, createReactAgent or model.bindTools.
+ * @param {object} [options]
+ * @param {typeof fetch} [options.fetch] fetch that pays x402 (wrapFetchWithPayment from @x402/fetch); plain fetch works with credit keys
+ * @param {{ presign?: string, doctor?: string }} [options.creditKeys] prepaid credit keys (x-credit-key) per service
+ * @param {string[]} [options.only] the tool names to include (default: all five)
+ * @param {boolean} [options.free] fall back to the free quick checks when a check can't be paid (default true)
+ * @param {string} [options.presignUrl] @param {string} [options.doctorUrl] @param {number} [options.timeoutMs]
+ */
+export function fizzlTools({ fetch: fetchImpl = globalThis.fetch, ...options } = {}) {
+  const defs = checks({ ...options, fetch: withUserAgent(fetchImpl) });
+  return Object.entries(defs).map(([name, d]) => tool(
+    async (input) => JSON.stringify(await d.execute(input)),
+    { name, description: d.description, schema: d.inputSchema },
+  ));
+}

package/package.json

@@ -1,6 +1,24 @@
-{
-  "name": "fizzl-langchain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "fizzl-langchain",
+  "version": "0.1.0",
+  "description": "Safety checks for LangChain.js and LangGraph.js agents that pay: tools to check a transaction or signature before signing, a token before buying, a wallet's open approvals, and an x402 endpoint before paying it (presign-guard and x402 Doctor, paid per call over x402, with a free quick check to try them).",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test test/*.test.mjs", "example": "node example/agent.mjs" },
+  "dependencies": { "presign-guard-ai-sdk": "^0.3.0" },
+  "peerDependencies": { "@langchain/core": ">=0.3.58 <2.0.0", "zod": "^3.25.0 || ^4.0.0" },
+  "devDependencies": { "@langchain/core": "^1.2.0", "@langchain/langgraph": "^1.0.0", "zod": "^4.0.0" },
+  "keywords": ["langchain", "langchainjs", "langgraph", "tools", "agents", "x402", "mpp", "wallet", "security", "presign", "token-check", "honeypot", "approvals", "permit2", "usdc", "base", "solana", "xrpl", "rlusd"],
+  "repository": { "type": "git", "url": "git+https://github.com/Fizzl13/x402-examples.git", "directory": "fizzl-langchain" },
+  "homepage": "https://github.com/Fizzl13/x402-examples/tree/main/fizzl-langchain#readme",
+  "license": "MIT"
+}