Metadata-Version: 2.4
Name: sweetai-agent-firewall
Version: 0.1.5
Summary: Pre-transaction trust firewall for AI agents: should-i-pay decisions, sybil forensics, liveness SLA (SweetAI x402 / ERC-8004)
Author-email: SweetAI <tiamatboss@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://sweetai.tiamatcrypto.com
Project-URL: Documentation, https://sweetai.tiamatcrypto.com/llms.txt
Project-URL: MCP, https://sweetai.tiamatcrypto.com/mcp
Project-URL: Source, https://sweetai.tiamatcrypto.com/agent.json
Keywords: x402,erc-8004,ai-agents,agent-payments,sybil,trust,mcp,crypto,usdc,base,solana,a2a
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# sweetai-agent-firewall

**Pre-transaction trust firewall for AI agents.** Before your agent sends USDC to another agent, get a machine-actionable `PAY / CAUTION / SKIP` decision plus `expected_loss_usd`. One decision costs **0.01 USDC** through x402; no API key or subscription.

## Complete 402 → settle → retry → PAY flow

```python
from sweetai_firewall import SweetAIFirewall

fw = SweetAIFirewall()
# Use the target you actually have: agent_id, solana_asset, seller_url or pay_to.
request = {"agent_id": 2290, "amount_usd": 25}
# request = {"seller_url": "https://api.example.com/x402", "amount_usd": 0.05}
# request = {"pay_to": "0x...", "amount_usd": 0.05}

# 1. The unpaid first call must return payment requirements.
first = fw.should_i_pay(**request)
if not first.payment_required:
    raise RuntimeError("Expected x402 payment requirements; transfer blocked")

# 2. HOST-SPECIFIC HOOK: settle first.raw with your own x402 wallet/client.
# This function is supplied by the host application, not by this SDK.
# It must return the exact X-PAYMENT value for the retry.
payment_header = settle_with_host_wallet(first.raw)

# 3. Retry with X-PAYMENT. Only a settled PAY verdict returns normally.
# CAUTION, SKIP, unpaid 402, HTTP errors and malformed responses all raise.
decision = fw.approve_transfer(**request, payment_header=payment_header)

# 4. Only here may the host application send USDC to the target agent.
print(decision.action, decision.confidence, decision.expected_loss_usd)
```

The SDK never asks for private keys and never settles either the SweetAI check or the target transfer. `settle_with_host_wallet` is intentionally host-specific: use your existing x402 payer, such as AgentKit or another wallet-owning agent runtime.

For a lower-level integration, pass the same value directly to `should_i_pay(..., payment_header=payment_header)`. The `payment_header` argument was added in **0.1.5**; earlier releases could read the initial 402 but could not complete the paid retry.

## Decision fields

```python
decision.action             # "PAY" after approve_transfer succeeds
decision.confidence         # 0.0 - 1.0
decision.expected_loss_usd  # expected loss sized to your transfer amount
decision.raw                # complete paid response
```

## What the verdict uses

- ERC-8004 / Solana-8004 on-chain feedback analytics
- Sybil forensics: reviewer concentration, ghost reviewers and bursts
- Liveness evidence where available
- For `seller_url` / `pay_to`: Bazaar demand (payers, calls, calls/payer, trend).
  `wallet_flow.status=not_available` means demand data does not see
  seller→payer round trips.
- x402 USDC payment on Base, Polygon, Arbitrum or Solana

## Utility calls

```python
fw.status()   # live index status
fw.pricing()  # current server-side prices
```

## MCP alternative

```json
{"mcpServers": {"sweetai-agent-intel": {"url": "https://sweetai.tiamatcrypto.com/mcp", "transport": "http"}}}
```

Docs: <https://sweetai.tiamatcrypto.com/llms.txt> · Manifest: <https://sweetai.tiamatcrypto.com/.well-known/x402>
