Metadata-Version: 2.4
Name: aegis-router
Version: 0.1.0
Summary: One-shot agent payments for Python APIs: x402 + MPP dual-rail, discovery docs, local revenue ledger, Aegis trust — wrap a FastAPI app in five lines.
Project-URL: Homepage, https://aegis.borisinc.com
Project-URL: Documentation, https://aegis.borisinc.com/merchants.md
Project-URL: Source, https://github.com/Donk338/aegis-router
Author-email: Boris Inc <donk.boris@mailfence.com>
License-Expression: MIT
Keywords: agent-payments,fastapi,machine-economy,micropayments,mpp,tempo,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.19
Requires-Dist: fastapi>=0.100
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4
Requires-Dist: pympp[server,tempo]>=0.9.1
Requires-Dist: x402>=2.14.0
Provides-Extra: aegis
Requires-Dist: aegis-buy>=0.1.1; extra == 'aegis'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: uvicorn>=0.30; extra == 'dev'
Description-Content-Type: text/markdown

# aegis-router

**One-shot agent payments for Python APIs.** Wrap a FastAPI app in five
lines so AI agents can discover it, trust it, and pay for it — **x402**
(USDC on Base) **and MPP** (Machine Payments Protocol, Tempo) from the same
route, with spec-current discovery docs, a local revenue ledger, and the
[Aegis](https://aegis.borisinc.com) trust layer built in.

```python
from fastapi import FastAPI
from aegis_router import PaidAPI

app = FastAPI()
api = PaidAPI(app, pay_to="0xYourAddress", realm="api.example.com")

@api.paid("$0.01", example={"result": "…"})
@app.get("/paid/search")
async def search(q: str):
    return {"result": do_search(q)}

api.install()
```

That route now:

- answers **402 Payment Required** with BOTH an x402 `payment-required`
  challenge and an MPP `WWW-Authenticate: Payment` challenge — buyers pay
  with whichever rail their client speaks;
- verifies x402 payments via your facilitator and MPP payments directly
  against Tempo RPC (replay-protected, no facilitator needed);
- appears in `/openapi.json` with `x-payment-info`, in a generated
  `/llms.txt`, and in `/.well-known/x402` — all derived from the same
  registry that charges, so **advertised price and wire price can never
  drift**;
- logs every call and every settlement (rail, payer, tx reference) to a
  local SQLite ledger — you know you're being paid, and by whom, from
  minute one;
- returns the *reason* in the 402 body when a payment fails, instead of
  silently not getting paid.

## Install

```bash
pip install aegis-router          # + aegis-buy client: pip install 'aegis-router[aegis]'
```

Python ≥ 3.11. Payments stack: the official [x402](https://pypi.org/project/x402/)
SDK and [pympp](https://pypi.org/project/pympp/) (Tempo Labs' MPP SDK).

## Why this and not a TypeScript router

- **Python-native.** FastAPI/Starlette middleware, not a Next.js proxy in
  front of your API.
- **Dual-rail, four networks.** x402 challenges on Base by default (bring
  your own facilitator for Solana/Polygon/Arbitrum accepts) plus MPP on
  Tempo — every payment standard you skip is a buyer who can't pay you.
- **Trust, not just payments.** Making an endpoint payable is table stakes;
  Aegis makes it *provably delivering*: register once and its verifiers
  continuously score your liveness, challenge validity, price honesty and
  actual paid delivery — a score buyers check before they spend.
- **A ledger in the box.** Other stacks tell you to watch your wallet.
- **Loud failures.** Buyers get told why a payment was rejected.

## Trust & discovery flywheel

```bash
aegis-router check https://api.example.com    # lint your live agent-payability
aegis-router submit https://api.example.com   # register with the Aegis trust hub ($0.05 via x402)
aegis-router summary                          # local revenue by rail
```

Then register with the scanners: [x402scan](https://www.x402scan.com/resources/register)
and [mppscan](https://www.mppscan.com/register).

## Configuration

| Argument | Default | Notes |
|---|---|---|
| `pay_to` | — | EVM address receiving USDC (x402, Base) |
| `realm` | — | Your public host, e.g. `api.example.com` |
| `mpp_recipient` | `pay_to` | Tempo address receiving Tempo USDC |
| `mpp_secret_key` | `MPP_SECRET_KEY` env | HMAC secret binding challenge ids; set it in production |
| `facilitator` | `https://facilitator.xpay.sh` | Any x402 facilitator |
| `network` | `eip155:8453` | x402 settlement network |
| `ledger_path` / `replay_path` | `./aegis-router-*.db` | SQLite files |
| `enable_mpp` / `enable_x402` | `True` | Run single-rail if you must |

Per-route: `api.price(path, price, method=, description=, example=,
input_example=, input_schema=, mpp=)` or the `@api.paid(...)` decorator.

## Agent-assisted setup

Point your coding agent at
**https://aegis.borisinc.com/merchants.md** and tell it:

> Read https://aegis.borisinc.com/merchants.md and follow the guide to make
> my API discoverable and payable by agents. Only ask me questions if you
> need input you can't determine yourself.

## License

MIT. Built and operated in production by [Boris Inc](https://borisinc.com) —
every borisinc.com service runs this exact stack on mainnet.
