tollwarden

# TollWarden

**A payment security firewall for [x402](https://x402.org) — screen every micropayment before it settles.**

[![x402](https://img.shields.io/badge/x402-v2-blue)](https://github.com/x402-foundation/x402)
[![network](https://img.shields.io/badge/settles%20on-Base%20(USDC)-0052FF)](https://docs.cdp.coinbase.com/x402/quickstart-for-sellers)
[![tests](https://img.shields.io/badge/tests-381%2F381-brightgreen)](test/run-tests.ts)
[![npm](https://img.shields.io/npm/v/@tollwarden/client?label=sdk)](https://www.npmjs.com/package/@tollwarden/client)
[![license](https://img.shields.io/badge/license-BUSL--1.1-lightgrey)](LICENSE)

Agents that pay over x402 get drained in predictable ways: secrets leak through payment metadata, captured authorizations get replayed, quoted prices get inflated, and poisoned web content tricks agents into paying addresses they never planned to pay. TollWarden is one `POST` before settlement that checks for all of it and returns **allow / flag / block** with machine-readable, per-check reasons — in **~0.6 ms**.

TollWarden is **advisory and non-custodial**: it never touches private keys, wallets, or funds. It wraps around whatever facilitator and wallet your agent already uses. And it's a first-class x402 seller itself — its endpoints are paid via the official x402 middleware, settle through the Coinbase CDP facilitator, and carry Bazaar discovery metadata.

```
Agent decides to pay ──► POST /v1/scan/outgoing ──► allow ──► wallet settles
                                   │
                                   ├──► flag  ──► agent pauses / confirms intent
                                   └──► block ──► wallet refuses (reason attached)
```

## Use it in 30 seconds

```bash
npm install @tollwarden/client    # TypeScript/Node
pip install tollwarden           # Python
```

```ts
import { TollWardenClient, TollWardenBlockedError } from "@tollwarden/client";
const tollwarden = new TollWardenClient({ agentId: "my-agent" }); // free API key auto-minted, 100 free scans

tollwarden.observe(fetchedPageText, { sourceUrl }); // tag what your agent just read → injection detection
await tollwarden.guardOutgoing(payment);            // throws TollWardenBlockedError on a block verdict
```

**New here? [Protect your x402 agent in 5 minutes →](QUICKSTART.md)**

The SDK ([`sdk/`](sdk/), zero dependencies) also verifies every verdict's Ed25519 attestation against a pinned key, tracks your free-call quota, and can subscribe to [plans](#api) autonomously. Wallet authors get standalone `verifyAttestation()` / `computePaymentCommitment()` — and the **enforcement kit**: `TollWardenEnforcer.guardSigner(account)` wraps any viem/ethers signer so it physically refuses to sign an x402 payment authorization without a fresh, payment-bound allow-verdict.

## Framework integrations

Building on an agent framework? TollWarden ships drop-in packages that give your agent "scan before you pay" in about two lines — a toolset plus a provenance mechanism that auto-tags what the agent reads, so the prompt-injection-triggered-payment detector works without any prompt engineering:

| Framework | Package | Install |
|---|---|---|
| LangChain | [`langchain-tollwarden`](integrations/langchain-tollwarden) | `pip install langchain-tollwarden` |
| CrewAI | [`crewai-tollwarden`](integrations/crewai-tollwarden) | `pip install crewai-tollwarden` |
| NeMo Agent Toolkit | [`nemo-tollwarden`](integrations/nemo-tollwarden) | `pip install nemo-tollwarden` |
| Coinbase AgentKit | [`agentkit-tollwarden`](integrations/agentkit-tollwarden) | `pip install agentkit-tollwarden` |
| Vercel AI SDK | [`@tollwarden/ai-sdk`](integrations/ai-sdk) | `npm install @tollwarden/ai-sdk` |

Each exposes the same three tools (scan / check reputation / report) plus a framework-native provenance hook — a callback (LangChain), an after-tool-call hook (CrewAI), an explicit `content` argument (NeMo), a wallet-aware action (AgentKit), or an `onStepFinish` handler (Vercel AI SDK) — and a `guarded_payment` / `guardedPayment` wrapper for enforcement by construction (the payment executor never runs on a block verdict). See each package's README for the two-line setup.

## What it catches

**Core detectors**

| Check | What it catches |
|---|---|
| PII / secret detection | EVM private keys, seed phrases, AWS/OpenAI/Anthropic/GitHub/Slack keys, JWTs, `?api_key=` URL credentials, SSNs, Luhn-validated card numbers, emails, phones — in `resource_url`, `description`, `reason`, and `metadata`, *before* they're transmitted |
| Replay detection | Nonce reuse (stale or captured payment authorizations), scoped `network:payer:nonce`, configurable TTL window |
| Overpayment detection | Above a configurable multiple of expected price (flag ≥3×, block ≥10×) plus an absolute ceiling |
| Prompt-injection-triggered payments | Payments whose *decision* originated from content the agent just read (tool result / fetched page) rather than its own planning step; escalates on weighted injection tells in that content (override/redirect phrasing across a broad verb/object corpus and in 8 languages: English, Spanish, Portuguese, French, German, Russian, Chinese, Japanese; spoofed system/chat-template/Guidance markers, smuggled model boundary tokens, fabricated conversation turns, concealment, business-email-compromise phrasing — "our payment address has changed, no need to verify" — and urgency pressure), with extra weight when a tell sits near an address-like token. Scored the way injections are shaped: weak tells only add up when they cluster, pressure alone (urgency, transcript form, hidden characters) never blocks, and a human's own "pay X to 0x…" instruction is not scored against them. Content is scanned both raw and with HTML tags, entities and markdown emphasis stripped, so `**Ignore** all <b>previous</b>&nbsp;instructions` reads as the sentence it renders as. Blocks when the `pay_to` address itself came from that content — even split across lines or separators, missing its `0x`, or laced with invisible characters |
| Resource URL risk (incoming) | IP-literal hosts, punycode/homoglyphs, link shorteners, `user@host` tricks, non-HTTPS, credential demands ("send your seed phrase") |
| Counterparty reputation | Shared post-hoc report registry, cross-checked on every scan; reporting is always free. Blocked injection scans also feed it automatically: a wallet caught being planted in just-read content (or used as vanity-bait) is flagged on every agent's future scans of it — one detection becomes network-wide protection (flag-only; scan inputs are client-supplied) |
| Delivery outcomes | Measured, commitment-bound delivery history per counterparty — a clean payment to a seller who never ships still fails you. Sellers with low delivery rates or repeated no-ships get flagged (never blocked: H-2 applies to measured history too) |

**Zero-latency hardening tier** — checks that hold even when the calling agent's narration is compromised:

| Check | What it catches |
|---|---|
| Velocity limits | ≥N scans/min (flag; block at 2×), cumulative hourly spend cap — rate and spend are observed facts, not self-reports. Scoped to the **account behind your API key**, so a fresh `agent_id` per request opens no new window; only anonymous scans fall back to `agent_id`/`payer` |
| First-contact size cap | First payment to a never-seen counterparty above a threshold |
| Asset verification | `asset` contract that isn't canonical USDC on the declared network (lookalike-token attack) |
| Merchant pinning (TOFU) | Two tiers. **Your account's own pin**: `pay_to` rotation on a domain *you* have paid before → block — nobody else can have written that record. **Shared observation**: the first address *any* caller presented for the domain; a mismatch there is a flag ("another caller saw a different address"), because both sides are client input — it becomes a block only once the non-blocking CDP Bazaar cross-check has verified the pinned address as the domain's merchant. Pin **age** and the **named** corroboration sources ship as signed attestation fields (see below), so a wallet can tell a four-minute-old pin from a six-month-old one instead of trusting both equally |
| Address poisoning | `pay_to` that matches a counterparty you have paid, your own pinned merchant, or a CDP-verified pin on its first + last characters but differs in the middle — the truncated-display ("0x2096…287C") vanity-address attack → block. A lookalike of an address some *other* caller merely presented → flag, so a stranger cannot seed a vanity "pin" and get your honest payment blocked as the lookalike. Also catches bait: a near-copy of the recipient or a trusted address *planted in the content the agent just read*. Blocked payments are rolled back out of trust state, so repeat attempts keep detecting |
| ScoutScore trust signal (opt-in) | Merchant domains rated LOW/VERY_LOW by [ScoutScore](https://scoutscore.ai) (spam farms, template clones, dead endpoints) → flag, clearly labeled as an external third-party signal. Lookups are async + cached (zero scan latency), share the domain only, and can never block on their own. Enable with `SCOUTSCORE=on` |
| Known-bad list | O(1) membership against a curated/synced badlist |
| Deep content analysis | Encoded/obfuscated injection payloads decoded and rescanned: base64 (both alphabets, line-wrapped, space-chunked, double-encoded), hex, percent-encoding, HTML entities, JS/JSON `\x`/`\u` escapes, Unicode tag-character smuggling ("invisible ASCII"), zero-width and homoglyph obfuscation (Cyrillic, Greek, IPA, small capitals, dotless-i — plus a mixed-script-word signal for lookalikes the fold table does not know), leetspeak (`1gn0re`) and letter-spacing (`i g n o r e`). Every pass is linear in the 200 KB content cap and guarded by a latency test. Bypassed below `MICRO_BYPASS_USD` (default $0.005) per payment, but drip-resistant: once cumulative scanned spend to a counterparty crosses the same threshold, the deep tie