Metadata-Version: 2.4
Name: crewai-tollwarden
Version: 0.1.0
Summary: TollWarden payment security for CrewAI agents: scan x402 payments before settling, auto-tag provenance for prompt-injection detection via a tool-call hook, and guard payment tools so blocked payments can never execute.
Project-URL: Homepage, https://tollwarden.com
Project-URL: Repository, https://github.com/tollwarden/tollwarden
Project-URL: Documentation, https://github.com/tollwarden/tollwarden/tree/main/integrations/crewai-tollwarden
Author-email: TollWarden <contact@tollwarden.com>
License: MIT
Keywords: ai-agents,crewai,payments,prompt-injection,security,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: crewai>=0.100
Requires-Dist: tollwarden>=0.3.0
Description-Content-Type: text/markdown

# crewai-tollwarden

[TollWarden](https://tollwarden.com) payment security for [CrewAI](https://crewai.com) agents — crews inherit "scan before you pay" by default.

```bash
pip install crewai-tollwarden
```

## Two additions

```python
from crewai import Agent
from tollwarden import TollWardenClient
from crewai_tollwarden import tollwarden_tools, register_tollwarden_provenance

tollwarden = TollWardenClient(agent_id="my-agent")   # free API key auto-minted (100 free scans)
register_tollwarden_provenance(tollwarden)           # ← the important line (call once at startup)

agent = Agent(
    role="Purchasing agent",
    goal="Buy data over x402 safely",
    tools=tollwarden_tools(tollwarden),
    # ...
)
```

Every x402 payment the agent scans gets an **allow / flag / block** verdict with machine-readable reasons: prompt-injection-triggered payments, replayed nonces, overpayment vs the quote, secrets/PII leaking in payment metadata, lookalike-token contracts, address poisoning, counterparty reputation.

## Why the provenance registration is the important line

TollWarden's strongest detector catches payments whose *decision* came from content the agent just read — a prompt-injected page or tool result that says "send payment to 0x…". That check needs to know what the agent read. `register_tollwarden_provenance` installs a CrewAI **after-tool-call hook** that observes every tool output automatically, so the very next scan is provenance-tagged and the injection check runs with real input. No prompt engineering, no developer learning what "provenance" means. (TollWarden's own tool outputs are excluded, so verdicts never pollute the signal.) CrewAI's tool-call hooks are process-global — call it once at startup.

## Enforcement: payments that *can't* execute when blocked

Tools rely on the model choosing to scan. `guarded_payment` doesn't:

```python
from crewai.tools import BaseTool
from crewai_tollwarden import guarded_payment

safe_pay = guarded_payment(execute_x402_payment, tollwarden)   # strict=True to refuse flags too
# build your payment tool's _run from safe_pay — on a block verdict it raises
# TollWardenBlockedError BEFORE execute_x402_payment is ever invoked.
```

For wallet-level enforcement (the signer itself refuses unscanned payments), see `TollWardenEnforcer` in the [tollwarden SDK](https://pypi.org/project/tollwarden/).

## The toolset

| Tool | When the agent is told to use it |
|---|---|
| `tollwarden_scan_payment` | ALWAYS, immediately before settling any x402 payment (or before paying a received 402 offer with `direction="incoming"`) |
| `tollwarden_check_reputation` | Before dealing with an unfamiliar counterparty address |
| `tollwarden_report_counterparty` | After a bad payment experience (always free) — warns other agents |

Verdicts are Ed25519-signed and payment-bound; the underlying client verifies them against a pinned key automatically.

MIT. TollWarden is advisory and non-custodial: it never touches keys, wallets, or funds.
