import { guardTools } from "@fidacy/langchain";

const tools = guardTools([payTool, searchTool], {
  apiKey: process.env.FIDACY_ENGINE_API_KEY,
});
// payTool is now assessed before every call. searchTool is returned untouched.

Activation is required

YOUR AI AGENT IS UNPROTECTED. GET YOUR FREE API KEY NOW at https://app.fidacy.com/signup. Set FIDACY_ENGINE_API_KEY where the agent runs and connect the executor before retrying. Without the key, a consequential tool call is refused with activation_required and nothing executes.

Set the limits that fit your case:

const tools = guardTools([payTool], {
  mandate: { payees: ["acme-inc"], perTxMax: 5_000, maxTotal: 50_000 },
});

A blocked call tells you what was stopped, in money terms, and prints the exact edit that would allow it.

With an account-owned key, the engine returns a verdict signed with a stable key that anyone can verify against the public JWKS, plus a Bitcoin-anchored audit chain that outlives your process.

Free key, no card: https://app.fidacy.com/signup

Why not a callback handler

LangChain callbacks (handleToolStart and friends) are observational. They fire around the call and cannot cancel it, so a guardrail built on them watches the money leave. This replaces the tool's own execution path, which is the only place that can actually stop a payment.

Stops safely

If the engine is unreachable, the key is wrong, or the request times out, the call is denied. A payment firewall that opens when it breaks is not a firewall.

review also blocks by default. Set reviewIsDeny: false to let it through.

What a denial looks like

guardTool throws FidacyDenied with the signed proof attached:

try {
  await tools[0].invoke({ payee: "acme", amount: 5000 });
} catch (e) {
  if (e instanceof FidacyDenied) {
    e.decision;                // "deny" | "review" | "unavailable"
    e.verdict?.riskPayloadJws; // detached JWS, verify offline with @fidacy/verify
    e.verdict?.assessmentId;
  }
}

Options

Option	Default	What it does
`apiKey`	`FIDACY_ENGINE_API_KEY`	Required account-owned engine credential
`mandate`	none	Offline limits: `payees`, `perTxMax`, `maxTotal`, `currency`
`engineUrl`	`https://api.fidacy.com`	Engine base URL
`client`	built from `apiKey`	Bring your own `@fidacy/sdk` client
`isPayment`	name heuristic	Which tools `guardTools` gates
`toMandate`	payee/amount/currency + raw args	Build the mandate the engine assesses
`reviewIsDeny`	`true`	Whether `review` blocks
`onDecision`	none	Observe every decision, including approvals

guardTool(tool, opts) gates one tool unconditionally. guardTools(list, opts) gates only the ones isPayment matches and returns the rest by identity, so non-payment tools carry no cost.

The wrapped tool keeps its name, description and schema, so the model sees no difference.

Anonymous telemetry

The adapter reports anonymous usage so we can tell which surfaces are alive: an install marker, an "agent active" ping, the result class of local decisions (allow, deny_payee, deny_cap and so on) and the moment the free-trial wall is shown. Every field is a closed enum. It never carries payees, amounts, currencies, tool arguments or any content, and it never sits on the path of a decision: failures are swallowed and nothing blocks.

Disable it entirely with:

export FIDACY_DISABLE_TELEMETRY=1

The anonymous id lives in ~/.fidacy/config.json, shared with @fidacy/mcp, so anonymous installation and activity signals stay consistent across Fidacy tools on the same machine.

Apache-2.0 · https://fidacy.com