Metadata-Version: 2.5
Name: fizzl
Version: 0.8.0
Summary: Safety checks for AI agents that pay: check a transaction or signature before signing, a token before buying, a wallet's approvals, and an x402 endpoint before paying it (presign-guard, x402 Doctor).
Project-URL: Homepage, https://github.com/Fizzl13/x402-examples/tree/main/fizzl-py
Project-URL: Repository, https://github.com/Fizzl13/x402-examples
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai-agents,approvals,base,honeypot,langchain,mcp,openai-agents,presign,rlusd,security,solana,token-check,usdc,wallet,x402,xrpl
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Requires-Dist: pydantic>=2; extra == 'langchain'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.3; (python_version >= '3.10') and extra == 'openai-agents'
Requires-Dist: pydantic>=2; extra == 'openai-agents'
Provides-Extra: x402
Requires-Dist: x402[requests]>=2.0; extra == 'x402'
Description-Content-Type: text/markdown

# fizzl

Safety checks for Python AI agents that pay: LangChain, LangGraph, the OpenAI Agents SDK, CrewAI or your own loop.

An [official LangChain integration](https://docs.langchain.com/oss/python/integrations/tools): listed in the LangChain docs under tools.

For LangChain.js and LangGraph.js: [`fizzl-langchain`](https://www.npmjs.com/package/fizzl-langchain) on npm.

| Check | 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). With `from_address` (the agent's wallet) a transaction is simulated, so a hidden approval, an NFT leaving or a transaction that would fail shows up; with `intent` (one sentence) signing something else than meant is caught; with `x402` (the accepts entry being paid) a payment that pays more or someone else is red | [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 market (orange) | presign-guard | $0.01 |
| `check_solana_transaction` | a **Solana** transaction before signing it: every instruction is read and the transaction simulated. Token account takeover (SetAuthority), System Assign (red); unlimited delegates, durable nonces, closing to someone else, hidden owner or delegate changes, a failing transaction (orange) | presign-guard | $0.01 |
| `check_message` | a plain message before `personal_sign` / `eth_sign`: eth_sign, a Sign-In with Ethereum message for another site (red); unreadable bytes, a sign-in for another URI, address or chain (orange) | presign-guard | $0.01 |
| `check_algorand_transaction` | an **Algorand** transaction or atomic group before signing it: every transaction your account sends is read and the group simulated. Rekey to another key, closing the account or an asset holding to someone else, fake USDC (red); clawbacks, risky opt-ins, app update/delete/clear-state, a partial group, a group that would fail (orange) | presign-guard | $0.01 |
| `check_token` | a token **before buying or accepting it**: honeypot, rug-pull signs, look-alikes (Solana, EVM, XRPL tokens as `CURRENCY.rIssuer`, and Algorand assets by id) | presign-guard | $0.01 |
| `check_wallet_approvals` | every open approval of a wallet and which to revoke | presign-guard | $0.02 |
| `screen_wallet` | a wallet address **before paying it or accepting money from it**: any chain's address (EVM, Solana, Tron, Bitcoin, XRPL, Algorand) against the OFAC SDN sanctions list, synced from the US Treasury, plus theft and phishing reports for EVM (red names the SDN entry) | presign-guard | $0.01 |
| `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 checks only check. They never sign, pay or move anything themselves. A failed check comes back as
`{"error": ..., "message": ...}` instead of raising, so the agent can tell its user.

## Install

```sh
pip install "fizzl[x402]"              # with the x402 client, to pay per check
pip install "fizzl[langchain,x402]"    # plus LangChain tools
pip install "fizzl[openai-agents]"     # OpenAI Agents SDK tools (Python 3.10+)
```

## Use

```python
import requests
from eth_account import Account
from x402 import x402ClientSync
from x402.http.clients import wrapRequestsWithPayment
from x402.mechanisms.evm.exact import ExactEvmScheme
from fizzl import Fizzl

payer = x402ClientSync().register("eip155:8453", ExactEvmScheme(Account.from_key(AGENT_KEY)))  # USDC on Base
session = wrapRequestsWithPayment(requests.Session(), payer)

fizzl = Fizzl(session=session)
fizzl.check_endpoint_before_paying("https://api.example.com/funding", max_usd=0.05)
# {'verdict': 'go', 'summary': 'OK to pay: $0.02 on Base.', 'options': [...], 'reasons': [], ...}
fizzl.check_token("base", "0x...")
fizzl.check_before_signing(type="approval", chainId=8453, token="0x...", spender="0x...", amount="115792089237316195423570985008687907853269984665640564039457584007913129639935")
```

**Try it without a wallet:** `Fizzl()` with no paying session and no credit keys falls back to the free quick checks for `check_token`, `check_before_signing`, `check_solana_transaction`, `check_algorand_transaction`, `check_message` and `check_endpoint_before_paying`: the verdict only, a few per hour, marked `"free": True` with a note on what the full check costs. `check_wallet_approvals`, `screen_wallet` and `check_xrpl_transaction` have no free version. `Fizzl(free=False)` returns `payment_required` instead.

**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 use a plain session:

```python
fizzl = Fizzl(credit_keys={"presign": PRESIGN_CREDIT_KEY, "doctor": DOCTOR_CREDIT_KEY})
```

## LangChain / LangGraph

```python
from langgraph.prebuilt import create_react_agent
from fizzl.langchain import fizzl_tools

tools = fizzl_tools(session=session)          # or credit_keys={...}; only=[...] for some of them
agent = create_react_agent(model, tools + your_tools,
    prompt="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.")
```

The tools are plain `StructuredTool`s with typed arguments, so CrewAI and other frameworks that take LangChain tools can use them too.

## OpenAI Agents SDK

```python
from agents import Agent, Runner
from fizzl.openai_agents import fizzl_tools

agent = Agent(name="buyer", tools=fizzl_tools(session=session),   # or credit_keys={...}, or nothing for the free checks
    instructions="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.")
print(Runner.run_sync(agent, "Is https://api.example.com/funding safe to pay, at most $0.05?").final_output)
```

The checks run in a worker thread, so a blocking `requests` session doesn't stall the agent's event loop. Bad
arguments from the model come back as `{"error": "bad_input", ...}` without calling (or paying for) the check.

## Want the wallet to enforce it, not just inform the model?

Tools inform the model; a model can still ignore them. To make red and over-budget payments impossible, guard the
wallet itself: [presign-guard-wallet](https://www.npmjs.com/package/presign-guard-wallet) (Node) checks every
signature with presign-guard and your spending limits, with Telegram approval above them.

## License

MIT
