Metadata-Version: 2.4
Name: aegis-buy
Version: 0.1.1
Summary: Trust-gated x402 buyer client — pay for machine-economy APIs safely (pre-payment trust gate, local spend policy, receipts ledger). Powered by Aegis (aegis.borisinc.com).
Author-email: Aegis <ouroboros@borisinc.com>
License: MIT
Project-URL: Homepage, https://aegis.borisinc.com
Keywords: x402,agent-commerce,usdc,base,micropayments,mcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: x402>=2
Requires-Dist: eth-account
Requires-Dist: cryptography
Provides-Extra: mcp
Requires-Dist: mcp; extra == "mcp"
Dynamic: license-file

# aegis-buy

**The trust layer for agent spending.** Wallets answer *"can my agent pay?"* —
aegis-buy answers *"should it pay, and did it get what it paid for?"*

Before your agent spends a cent: a **trust gate backed by real delivery
verification** ([Aegis](https://aegis.borisinc.com) actually buys from sellers
with real USDC to prove they deliver — the only x402 index that does), a
**local spend policy** (per-call/daily caps, tier floors, allow/deny lists),
and an **Ed25519-signed receipt** for every purchase. Procurement mode is
capture-on-delivery: state a need and a budget, and you are never charged
for non-delivery.

Works with any funded Base wallet key — including one from Coinbase Agentic
Wallets — on top of your wallet, not instead of it.

```
probe (free) -> parse price -> Aegis trust gate -> local spend policy -> pay -> receipt
```

Every step before "pay" is free and local. Nothing settles unless the service
passes the trust gate **and** your policy caps.

## Why not just a wallet?

Agent wallets (Coinbase Agentic Wallets, AgentCash, Bedrock AgentCore) give your
agent the *ability* to pay and cap *how much*. None of them answer whether the
seller on the other side is real: in the x402 ecosystem roughly half of listed
endpoints are unreachable at any given time, and "challenge-honest,
delivery-broken" sellers settle your payment and 404 the paid retry. aegis-buy
gates on the only signal that catches that — verified paid deliveries — and its
trust verdicts conform to the x402 trust-provider extension wire format
(`x402-trust-evaluation-v0.1`), so the same data can gate settlements
server-side as the extension lands.

## Install

```bash
pip install aegis-buy            # library
pip install 'aegis-buy[mcp]'     # + MCP server (aegis-buy-mcp)
```

## Quickstart

```python
from aegis_buy import BuyClient

client = BuyClient()  # key from AEGIS_BUY_KEY env
r = client.get("https://api.example.com/price?symbol=ETH")
print(r["ok"], r["price_usd"], r["data"])

# Don't know a provider? Let the hub find a trusted one within budget:
r = client.procure("live ETH price", budget=0.01)

# Test everything without spending a cent:
client = BuyClient(dry_run=True)
```

### Environment variables

| Var | Meaning | Default |
|---|---|---|
| `AEGIS_BUY_KEY` | EVM private key of the buyer wallet (funds USDC on Base) | — |
| `AEGIS_BUY_POLICY` | Path to spend policy JSON | `~/.aegis-buy/policy.json` |
| `AEGIS_BUY_LEDGER` | Path to sqlite receipts ledger | `~/.aegis-buy/ledger.db` |
| `AEGIS_HUB` | Aegis hub base URL | `https://aegis.borisinc.com` |
| `AEGIS_BUY_DRY_RUN` | `1` = MCP server never actually pays | off |

### Spend policy (`~/.aegis-buy/policy.json`)

```json
{
  "max_per_call_usd": 0.05,
  "max_per_day_usd": 1.00,
  "max_total_usd": 10.00,
  "min_tier": "provisional",
  "allow_domains": [],
  "deny_domains": ["sketchy.example"],
  "trust_mode": "basic"
}
```

- `max_per_call_usd` / `max_per_day_usd` / `max_total_usd` — hard USD caps. Day and
  total spend are computed from the local ledger.
- `min_tier` — minimum Aegis trust tier: `unverified` < `provisional` < `trusted`.
  Services flagged by Aegis are **always** blocked.
- `allow_domains` / `deny_domains` — domain allow/deny lists (subdomains match).
- `trust_mode` — `basic` (free Aegis signals), `strict` (paid $0.002 verification-backed
  trust check per service, itself policy-capped), or `off`.

Missing file = safe defaults (5¢/call, $1/day, provisional+, basic gate).

## MCP server

Give Claude Desktop (or any MCP client) a safe x402 wallet:

```json
{
  "mcpServers": {
    "aegis-buy": {
      "command": "aegis-buy-mcp",
      "env": {
        "AEGIS_BUY_KEY": "0xYOUR_BUYER_WALLET_PRIVATE_KEY",
        "AEGIS_BUY_POLICY": "~/.aegis-buy/policy.json"
      }
    }
  }
}
```

Tools: `buy_get(url, params_json)` · `procure(need, budget)` · `trust_gate(url)` · `spend_stats()`.

## Safety model

1. **Local spend policy** — per-call, per-day, and lifetime USD caps enforced before
   any payment; domain allow/deny lists. The wallet's downside is bounded by config.
2. **Pre-payment trust gate** — services are checked against Aegis's continuously
   verified registry *before* money moves. Unknown services default to `unverified`;
   flagged services are always blocked.
3. **Receipts ledger** — every attempt (paid, blocked, failed, dry-run) lands in a
   local sqlite ledger; caps are computed from it, so they survive restarts.
4. **No blind buys** — if the price can't be parsed from the 402 challenge, the
   purchase is refused.
5. **Delivery protection via Aegis** — routes purchased through the hub use
   auth-then-capture: your payment only settles after the upstream actually
   delivers, so you are never charged for non-delivery.

Use a **dedicated buyer wallet** funded with only what you're willing to spend —
defense in depth on top of the policy caps.

## Links

- Hub: https://aegis.borisinc.com — free discovery: `GET /discover?query=...`
- x402 protocol: HTTP 402 + USDC on Base (`eip155:8453`)

MIT license.

## LangChain
```python
from aegis_buy.langchain_adapter import get_tools
tools = get_tools()  # buy_get, procure, trust_gate, spend_stats
```
