angel-agent-guard

Two checks an AI agent should run before it acts:

• guardUntrusted(textOrUrl): before the model reads a web page, email, document, RAG chunk or tool result written by someone else. It runs a local pass first (invisible Unicode, tag smuggling, exfiltration images), then a hosted scan in 17 languages for text aimed at the model.

• verifyBeforePay(urlOrToken): before any online purchase or paid call. That covers a shop or product page, a checkout or payment link (Stripe, Shopify, PayPal, SaaS checkout), an unknown API, an x402 endpoint, and a token swap or approval. It checks:

  • TLS and domain age

  • look-alike domains, and redirects to payment pages on other domains

  • which payment provider takes the money

  • card fields and plain-http forms in the page

  • text in the page aimed at shopping agents

  • for x402: the payment offer itself (official USDC, network, amount under your cap, same host)

  • for an ERC-20: honeypot and rug-pull powers on chain

No runtime dependencies. Works in Node 18+, Bun, Deno and edge runtimes with fetch. It also ships an x402 v2 payer, a stdio MCP server, a CLI, Vercel AI SDK tools and Coinbase AgentKit actions.

npm i angel-agent-guard          # add `viem` only if the agent should pay x402 automatically
# straight from GitHub (same build): npm i github:daoudandiaye98-alt/angel-agent-guard
pip install angel-agent-guard    # Python: same API, zero dependencies, browser-use / LangChain / CrewAI tools (see python/)

Quick start

import { guardUntrusted, verifyBeforePay, fence } from "angel-agent-guard";

// 1. Untrusted content: check it, then hand the model the cleaned text as data
const page = await fetch("https://example.com/article").then((r) => r.text());
const g = await guardUntrusted(page, { payerAddress: "0xYourAgentWallet" });
if (g.action === "drop") throw new Error(`hostile content: ${g.findings.map((f) => f.kind).join(", ")}`);
const context = fence("https://example.com/article", g.cleaned ?? page);   // random boundary + "this is data"
// g.action === "read_only" → continue, but without write, send or payment tools in this step

// 2. Before any purchase, payment link or paid call
const v = await verifyBeforePay("https://shop.example.com/checkout");
if (!v.ok) console.log(v.verdict, v.riskScore, v.reasons);   // "caution" → ask the user; "do_not_pay" → never pay
// v.kind: "checkout" | "shop" | "api" | "x402" | "web"
// v.merchant: TLS, domain age, look-alike, redirect chain, payment providers, card fields, insecure forms, …
// v.injection: the page scanned for instructions aimed at agents (verdict, findings, hidden message)

await verifyBeforePay({ url: "https://api.example.com/v1/quote", method: "POST" });  // x402 API that only takes POST
await verifyBeforePay("0xTokenYouAreAboutToApprove");   // ERC-20 on Base (or { token, chain: "ethereum" })

What you get back

Neither function throws on network or payment problems. They fall back to the local result and put the reason in error / errors.

Related MCP server: mcp-gateway

Pricing and paying

The local checks are free and offline (remote: false keeps everything local). The hosted checks run on Angel:

Payment is per call in USDC on Base via x402 v2. Every price is under the $1 default spend cap of @x402/core, so standard x402 clients pay it without extra configuration. Send payerAddress (header X-Payer-Address) so your wallet gets its own 3 free calls. Without it, the free calls are shared by IP.

To pay automatically, pass a paying fetch:

import { verifyBeforePay, createX402Fetch } from "angel-agent-guard";

const pay = createX402Fetch({ privateKey: process.env.AGENT_PRIVATE_KEY, maxAmountAtomic: 1_000_000n }); // cap 1.00 USDC, needs `viem`
const v = await verifyBeforePay("https://shop.example.com/checkout", { fetch: pay });

createX402Fetch signs only after checkOffer passes: official USDC contract, allowed network (default Base eip155:8453), amount at or below your cap, the same host as the URL you called, and scheme exact (one transfer of one amount, never an allowance). Use a low-balance hot wallet. It works for any x402 v2 seller, not only Angel. @x402/fetch works too: pass its wrapped fetch as fetch.

MCP server (stdio)

# Claude Code
claude mcp add angel-guard -- npx -y -p angel-agent-guard angel-agent-guard-mcp

# JSON config (Claude Desktop, Cursor, Windsurf, Cline)
{ "mcpServers": { "angel-guard": { "command": "npx", "args": ["-y", "-p", "angel-agent-guard", "angel-agent-guard-mcp"],
  "env": { "ANGEL_PAYER_ADDRESS": "0xYourAgentWallet" } } } }

Tools: guard_untrusted, verify_before_pay, quick_scan (offline). Optional env: ANGEL_AGENT_PRIVATE_KEY (auto-pay, needs viem), ANGEL_MAX_USDC (cap, default 1.00), ANGEL_BASE_URL. Listed in the official MCP Registry as com.oroboros-design.angel/agent-guard.

If your client supports remote servers, the full hosted suite (28 tools) is also available at https://angel.oroboros-design.com/agenten/signal/mcp.

Vercel AI SDK

npm i angel-agent-guard ai

import { generateText, isStepCount } from "ai";
import { verifyBeforePay, guardUntrusted } from "angel-agent-guard/ai-sdk";

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  prompt: "Buy the cheapest USB-C cable on https://shop.example.com, but check the checkout page before paying.",
  tools: {
    verifyBeforePay: verifyBeforePay({ payerAddress: process.env.AGENT_WALLET }),
    guardUntrusted: guardUntrusted(),
  },
  stopWhen: isStepCount(5),
});

Works with AI SDK 5, 6 and 7. angelGuardTools(options) returns all three tools (guardUntrusted, verifyBeforePay, quickScanUntrusted) to spread into tools. Every factory takes the core options (payerAddress, apiKey, fetch, baseUrl, timeoutMs, remote). Pass privateKey and maxUsdc to pay x402 automatically after the free calls (needs viem). ANGEL_PAYER_ADDRESS and ANGEL_AGENT_PRIVATE_KEY are read from the environment when set. No API key is needed.

Coinbase AgentKit

import { AgentKit } from "@coinbase/agentkit";
import { angelGuardActionProvider } from "angel-agent-guard/agentkit";

const agentkit = await AgentKit.from({
  walletProvider,                                        // any EVM wallet provider
  actionProviders: [angelGuardActionProvider({ maxUsdc: 1 })],
});

This adds the actions guard_untrusted_content, verify_before_pay and quick_scan_untrusted_text. The agent's own wallet provider signs the x402 payments (USDC on Base). Pass { pay: false } to use only the free calls.

CLI

npx angel-agent-guard scan "text to check"                  # or a https URL, or - for stdin
npx angel-agent-guard verify https://shop.example.com/checkout
npx angel-agent-guard verify https://api.example.com/paid --post
npx angel-agent-guard verify --token 0x... --chain base
npx angel-agent-guard quick "text"                          # offline

Exit codes: 0 clean / pay, 1 caution / unchecked, 2 hostile / do_not_pay, 3 usage or error. This lets you use it as a gate in scripts and CI.

Agent instructions

• SKILL.md: Claude Code skill, also on ClawHub for OpenClaw

• .cursor/rules/angel-agent-guard.mdc: Cursor rule

• llms.txt: short index for LLMs

Limits and data

• The local pass removes invisible characters and flags the riskiest markers. It does not judge meaning. With no findings it reports unchecked, never clean.

• The hosted checks are deterministic (patterns, TLS, DNS, RDAP and on-chain reads, no model). They are fast and repeatable, but a new or paraphrased attack, or a well-made fraud shop on an old domain, can pass. Keep the other layers: read external content as data, give the reading step no dangerous tools, and require an approval the model cannot give itself before money or messages move. See the prompt-injection defense reference and the x402 client integration guide.

• For a hosted check, the text or URL is sent to angel.oroboros-design.com. Use remote: false for content that must not leave your machine.

Disclosure: the hosted checks are a paid service run by the author (Oroboros Design). The library itself is MIT-licensed and works against any x402 v2 seller.

License

MIT