payagent 0.1.0__tar.gz

payagent-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+*.md.bak
+.idea/
+.vscode/
+*.swp
+.python-version
+*.db
+*.sqlite
+*.sqlite3
+agent_pay_spend.db

payagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 poqdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

payagent-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: payagent
+Version: 0.1.0
+Summary: Universal Payment & Monetization Engine for AI Agents — HTTP 402, multi-rail wallets, budget guardrails, escrow, and @paywall for FastAPI/MCP.
+Project-URL: Homepage, https://github.com/pomoq-dev/payagent
+Project-URL: Repository, https://github.com/pomoq-dev/payagent
+Project-URL: Issues, https://github.com/pomoq-dev/payagent/issues
+Project-URL: Changelog, https://github.com/pomoq-dev/payagent/releases
+Author-email: poqdev <poqdev@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,crypto-wallet,escrow,http-402,mcp,monetization,payagent,payments,paywall,solana,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: starlette>=0.36; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: starlette>=0.36; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# payagent
+
+**Universal Payment & Monetization Engine for AI Agents**
+
+[![PyPI](https://img.shields.io/pypi/v/payagent.svg)](https://pypi.org/project/payagent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/pomoq-dev/payagent/test.yml?branch=main&label=CI)](https://github.com/pomoq-dev/payagent/actions)
+[![Python](https://img.shields.io/pypi/pyversions/payagent.svg)](https://pypi.org/project/payagent/)
+
+Enable AI agents to **pay each other** for APIs, data, and compute — and let developers **monetize MCP tools / endpoints** with a one-line decorator.
+
+| Capability | What you get |
+|------------|----------------|
+| **HTTP 402** | Client auto-detects `Payment Required`, settles, retries with proof |
+| **Multi-rail wallet** | x402 (Base/EVM), Solana SOL/USDC, fiat adapter (Payman-style) |
+| **Guardrails** | Per-tx / daily / monthly limits, domain allowlist, HITL threshold |
+| **Escrow** | Lock → job → validate → release or refund |
+| **`@paywall`** | Monetize FastAPI / Starlette / MCP HTTP routes in ~2 lines |
+
+---
+
+## Architecture
+
+```text
+┌─────────────┐     AgentPayClient      ┌──────────────────────────────┐
+│  Agent A    │ ──────────────────────► │  Agent B (FastAPI / MCP)     │
+│  (buyer)    │   GET /premium-data     │                              │
+│             │ ◄──── HTTP 402 ──────── │  @paywall(price_usd=0.05)    │
+│  AgentWallet│                         │  X-PAYMENT-ADDRESS / AMOUNT  │
+│  + policy   │ ── pay(USDC) via x402 ─►│                              │
+│             │ ── retry + X-PAYMENT-PROOF ──►  verify → 200 + data    │
+└─────────────┘                         └──────────────────────────────┘
+        │
+        ├── providers/x402.py    (Base / EVM)
+        ├── providers/solana.py  (SOL / SPL USDC)
+        ├── providers/fiat.py    (Payman / Stripe-like REST)
+        ├── guardrails.py        (budgets + allowlist + HITL)
+        └── escrow.py            (conditional release)
+```
+
+---
+
+## Install
+
+```bash
+pip install payagent
+# or
+uv add payagent
+
+# FastAPI seller extras
+pip install 'payagent[fastapi]'
+```
+
+From GitHub:
+
+```bash
+pip install "git+https://github.com/pomoq-dev/payagent.git@v0.1.0"
+```
+
+---
+
+## Quickstart
+
+### 1) Buyer — auto-pay on HTTP 402
+
+```python
+import asyncio
+from payagent import AgentPayClient, AgentWallet, SpendingPolicy
+
+async def main():
+    wallet = AgentWallet.mock(
+        policy=SpendingPolicy(max_per_tx=0.50, daily_limit=10.0, monthly_limit=100.0),
+        balance=50.0,
+    )
+    async with AgentPayClient(wallet) as client:
+        resp = await client.get("https://api.seller.example/premium-data")
+        print(resp.status_code, resp.json())
+        print("settled via", client.last_payment)
+
+asyncio.run(main())
+```
+
+### 2) Seller — monetize with `@paywall`
+
+```python
+from fastapi import FastAPI, Request
+from payagent import paywall
+
+app = FastAPI()
+
+@app.get("/premium-data")
+@paywall(price_usd=0.05, recipient_address="0xYourAddress", currency="USDC")
+async def premium(request: Request):
+    return {"data": "secret sauce"}
+```
+
+### 3) Guardrails
+
+```python
+from payagent import AgentWallet, SpendingPolicy
+
+policy = SpendingPolicy(
+    max_per_tx=0.50,
+    daily_limit=10.0,
+    monthly_limit=100.0,
+    allowlist_domains=["api.partner.com", "mcp.internal"],
+    require_human_approval_above=2.0,
+)
+wallet = AgentWallet.mock(policy=policy)
+```
+
+### 4) Escrow
+
+```python
+from payagent import AgentWallet, EscrowSession, SpendingPolicy
+
+wallet = AgentWallet.mock(policy=SpendingPolicy(max_per_tx=5.0, daily_limit=50.0))
+escrow = EscrowSession(wallet, validator_fn=lambda r: r.get("ok") is True)
+
+result = await escrow.run(
+    job=lambda: {"ok": True, "answer": 42},
+    amount=0.25,
+    currency="USDC",
+    recipient="0xProvider",
+)
+```
+
+---
+
+## Feature support matrix
+
+| Rail | Module | Currencies | Live chain | Mock (tests) |
+|------|--------|------------|------------|--------------|
+| **x402 / Base / EVM** | `X402Provider` | USDC, ETH, WETH, BASE-USDC | optional RPC + key | default `mock=True` |
+| **Solana** | `SolanaProvider` | SOL, USDC, SOL-USDC | optional RPC + key | default `mock=True` |
+| **Fiat** | `FiatProvider` | USD, EUR, GBP, FIAT | Payman-style REST | default `mock=True` |
+| **HTTP 402 client** | `AgentPayClient` | via wallet routing | httpx | `respx` in tests |
+| **Paywall** | `@paywall` | any string currency | proof verify | mock verifier |
+| **Escrow** | `EscrowSession` | any wallet currency | same rails | full unit coverage |
+
+---
+
+## Project layout
+
+```text
+src/payagent/
+  client.py       # 402 interceptor client
+  wallet.py       # multi-provider AgentWallet
+  guardrails.py   # SpendingPolicy + ledger
+  escrow.py       # conditional payments
+  paywall.py      # @paywall decorator
+  exceptions.py
+  providers/
+    base.py x402.py solana.py fiat.py
+```
+
+---
+
+## Configuration
+
+Copy `.env.example` → `.env` (never commit secrets):
+
+```bash
+SOLANA_PRIVATE_KEY=...
+BASE_PRIVATE_KEY=0x...
+PAYMAN_API_KEY=...
+PAYAGENT_DAILY_LIMIT=10.0
+```
+
+---
+
+## Develop
+
+```bash
+uv venv -p 3.13 .venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+pytest -q
+mypy src/payagent
+python -m build
+```
+
+```bash
+python examples/agent_buyer.py
+python examples/escrow_job.py
+# uvicorn examples.agent_seller_fastapi:app --port 8000
+```
+
+---
+
+## Publish (PyPI)
+
+1. Create public repo `payagent` under `pomoq-dev`.
+2. PyPI Trusted Publisher or secret `PYPI_API_TOKEN`.
+3. GitHub Release `v0.1.0` → Actions uploads the wheel.
+
+Local: `PYPI_TOKEN=pypi-… ./scripts/publish.sh`
+
+---
+
+## License
+
+MIT © poqdev

payagent-0.1.0/README.md

@@ -0,0 +1,203 @@
+# payagent
+
+**Universal Payment & Monetization Engine for AI Agents**
+
+[![PyPI](https://img.shields.io/pypi/v/payagent.svg)](https://pypi.org/project/payagent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/pomoq-dev/payagent/test.yml?branch=main&label=CI)](https://github.com/pomoq-dev/payagent/actions)
+[![Python](https://img.shields.io/pypi/pyversions/payagent.svg)](https://pypi.org/project/payagent/)
+
+Enable AI agents to **pay each other** for APIs, data, and compute — and let developers **monetize MCP tools / endpoints** with a one-line decorator.
+
+| Capability | What you get |
+|------------|----------------|
+| **HTTP 402** | Client auto-detects `Payment Required`, settles, retries with proof |
+| **Multi-rail wallet** | x402 (Base/EVM), Solana SOL/USDC, fiat adapter (Payman-style) |
+| **Guardrails** | Per-tx / daily / monthly limits, domain allowlist, HITL threshold |
+| **Escrow** | Lock → job → validate → release or refund |
+| **`@paywall`** | Monetize FastAPI / Starlette / MCP HTTP routes in ~2 lines |
+
+---
+
+## Architecture
+
+```text
+┌─────────────┐     AgentPayClient      ┌──────────────────────────────┐
+│  Agent A    │ ──────────────────────► │  Agent B (FastAPI / MCP)     │
+│  (buyer)    │   GET /premium-data     │                              │
+│             │ ◄──── HTTP 402 ──────── │  @paywall(price_usd=0.05)    │
+│  AgentWallet│                         │  X-PAYMENT-ADDRESS / AMOUNT  │
+│  + policy   │ ── pay(USDC) via x402 ─►│                              │
+│             │ ── retry + X-PAYMENT-PROOF ──►  verify → 200 + data    │
+└─────────────┘                         └──────────────────────────────┘
+        │
+        ├── providers/x402.py    (Base / EVM)
+        ├── providers/solana.py  (SOL / SPL USDC)
+        ├── providers/fiat.py    (Payman / Stripe-like REST)
+        ├── guardrails.py        (budgets + allowlist + HITL)
+        └── escrow.py            (conditional release)
+```
+
+---
+
+## Install
+
+```bash
+pip install payagent
+# or
+uv add payagent
+
+# FastAPI seller extras
+pip install 'payagent[fastapi]'
+```
+
+From GitHub:
+
+```bash
+pip install "git+https://github.com/pomoq-dev/payagent.git@v0.1.0"
+```
+
+---
+
+## Quickstart
+
+### 1) Buyer — auto-pay on HTTP 402
+
+```python
+import asyncio
+from payagent import AgentPayClient, AgentWallet, SpendingPolicy
+
+async def main():
+    wallet = AgentWallet.mock(
+        policy=SpendingPolicy(max_per_tx=0.50, daily_limit=10.0, monthly_limit=100.0),
+        balance=50.0,
+    )
+    async with AgentPayClient(wallet) as client:
+        resp = await client.get("https://api.seller.example/premium-data")
+        print(resp.status_code, resp.json())
+        print("settled via", client.last_payment)
+
+asyncio.run(main())
+```
+
+### 2) Seller — monetize with `@paywall`
+
+```python
+from fastapi import FastAPI, Request
+from payagent import paywall
+
+app = FastAPI()
+
+@app.get("/premium-data")
+@paywall(price_usd=0.05, recipient_address="0xYourAddress", currency="USDC")
+async def premium(request: Request):
+    return {"data": "secret sauce"}
+```
+
+### 3) Guardrails
+
+```python
+from payagent import AgentWallet, SpendingPolicy
+
+policy = SpendingPolicy(
+    max_per_tx=0.50,
+    daily_limit=10.0,
+    monthly_limit=100.0,
+    allowlist_domains=["api.partner.com", "mcp.internal"],
+    require_human_approval_above=2.0,
+)
+wallet = AgentWallet.mock(policy=policy)
+```
+
+### 4) Escrow
+
+```python
+from payagent import AgentWallet, EscrowSession, SpendingPolicy
+
+wallet = AgentWallet.mock(policy=SpendingPolicy(max_per_tx=5.0, daily_limit=50.0))
+escrow = EscrowSession(wallet, validator_fn=lambda r: r.get("ok") is True)
+
+result = await escrow.run(
+    job=lambda: {"ok": True, "answer": 42},
+    amount=0.25,
+    currency="USDC",
+    recipient="0xProvider",
+)
+```
+
+---
+
+## Feature support matrix
+
+| Rail | Module | Currencies | Live chain | Mock (tests) |
+|------|--------|------------|------------|--------------|
+| **x402 / Base / EVM** | `X402Provider` | USDC, ETH, WETH, BASE-USDC | optional RPC + key | default `mock=True` |
+| **Solana** | `SolanaProvider` | SOL, USDC, SOL-USDC | optional RPC + key | default `mock=True` |
+| **Fiat** | `FiatProvider` | USD, EUR, GBP, FIAT | Payman-style REST | default `mock=True` |
+| **HTTP 402 client** | `AgentPayClient` | via wallet routing | httpx | `respx` in tests |
+| **Paywall** | `@paywall` | any string currency | proof verify | mock verifier |
+| **Escrow** | `EscrowSession` | any wallet currency | same rails | full unit coverage |
+
+---
+
+## Project layout
+
+```text
+src/payagent/
+  client.py       # 402 interceptor client
+  wallet.py       # multi-provider AgentWallet
+  guardrails.py   # SpendingPolicy + ledger
+  escrow.py       # conditional payments
+  paywall.py      # @paywall decorator
+  exceptions.py
+  providers/
+    base.py x402.py solana.py fiat.py
+```
+
+---
+
+## Configuration
+
+Copy `.env.example` → `.env` (never commit secrets):
+
+```bash
+SOLANA_PRIVATE_KEY=...
+BASE_PRIVATE_KEY=0x...
+PAYMAN_API_KEY=...
+PAYAGENT_DAILY_LIMIT=10.0
+```
+
+---
+
+## Develop
+
+```bash
+uv venv -p 3.13 .venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+pytest -q
+mypy src/payagent
+python -m build
+```
+
+```bash
+python examples/agent_buyer.py
+python examples/escrow_job.py
+# uvicorn examples.agent_seller_fastapi:app --port 8000
+```
+
+---
+
+## Publish (PyPI)
+
+1. Create public repo `payagent` under `pomoq-dev`.
+2. PyPI Trusted Publisher or secret `PYPI_API_TOKEN`.
+3. GitHub Release `v0.1.0` → Actions uploads the wheel.
+
+Local: `PYPI_TOKEN=pypi-… ./scripts/publish.sh`
+
+---
+
+## License
+
+MIT © poqdev

payagent-0.1.0/examples/agent_buyer.py

@@ -0,0 +1,47 @@
+"""Buyer agent: call a paid API with automatic HTTP 402 settlement.
+
+Run (mock — no real keys needed)::
+
+    python examples/agent_buyer.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from payagent import AgentPayClient, AgentWallet, SpendingPolicy
+
+
+async def main() -> None:
+    policy = SpendingPolicy(
+        max_per_tx=0.50,
+        daily_limit=10.0,
+        monthly_limit=100.0,
+        allowlist_domains=[],  # empty = allow all when allow_all_when_empty_allowlist
+        require_human_approval_above=5.0,
+    )
+    wallet = AgentWallet.mock(policy=policy, balance=50.0)
+
+    # Point at your seller (see agent_seller_fastapi.py). Uses mock wallet locally.
+    # For a dry demo without a live server we just show wallet payment:
+    result = await wallet.pay(
+        amount=0.05,
+        currency="USDC",
+        recipient="0xSellerDemoAddress",
+        domain="api.example.com",
+        memo="demo-purchase",
+    )
+    print("Paid:", result.tx_hash, result.amount, result.currency, "via", result.provider)
+    print("Proof header:", result.as_proof_header())
+    print("Daily remaining:", wallet.enforcer.remaining_daily())
+
+    # Real 402 flow (uncomment when seller is running):
+    # async with AgentPayClient(wallet) as client:
+    #     resp = await client.get("http://127.0.0.1:8000/premium-data")
+    #     print(resp.status_code, resp.json())
+
+    await wallet.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

payagent-0.1.0/examples/agent_seller_fastapi.py

@@ -0,0 +1,56 @@
+"""Seller: monetize a FastAPI endpoint with @paywall (2 lines).
+
+Install extras::
+
+    pip install 'payagent[fastapi]' uvicorn
+
+Run::
+
+    uvicorn examples.agent_seller_fastapi:app --reload --port 8000
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from payagent import PaymentVerifier, X402Provider, paywall
+
+try:
+    from fastapi import FastAPI, Request
+except ImportError as exc:  # pragma: no cover
+    raise SystemExit("Install fastapi: pip install 'payagent[fastapi]' uvicorn") from exc
+
+app = FastAPI(title="payagent seller demo")
+
+# Mock verifier — swap for AgentWallet / live provider in production
+_verifier = PaymentVerifier(providers=[X402Provider(mock=True)], mock_accept_all=False)
+# Accept any well-formed proof in this demo (see PaymentVerifier fallback),
+# or set mock_accept_all=True for the simplest local loop.
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/premium-data")
+@paywall(
+    price_usd=0.05,
+    recipient_address="0xSellerDemoAddress",
+    currency="USDC",
+    network="base",
+    verifier=PaymentVerifier(mock_accept_all=True),  # demo-only
+)
+async def premium_data(request: Request) -> dict[str, Any]:
+    return {
+        "data": "premium market signal",
+        "paid": True,
+        "client": request.client.host if request.client else None,
+    }
+
+
+@app.get("/mcp-tool-result")
+@paywall(price_usd=0.01, recipient_address="0xSellerDemoAddress")
+async def mcp_style_tool() -> dict[str, str]:
+    """Same decorator works for MCP/HTTP tool endpoints."""
+    return {"tool": "search", "result": "top hit"}

payagent-0.1.0/examples/escrow_job.py

@@ -0,0 +1,67 @@
+"""Escrow: lock funds → run job → validate → release or refund.
+
+Run::
+
+    python examples/escrow_job.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from payagent import AgentWallet, EscrowSession, EscrowValidationError, SpendingPolicy
+
+
+async def expensive_compute() -> dict[str, Any]:
+    # Pretend we called a remote model / data API
+    return {"status": "ok", "summary": "agent completed task", "tokens": 1200}
+
+
+def validate_result(result: dict[str, Any]) -> bool:
+    return result.get("status") == "ok" and "summary" in result
+
+
+async def main() -> None:
+    wallet = AgentWallet.mock(
+        policy=SpendingPolicy(max_per_tx=2.0, daily_limit=20.0, monthly_limit=200.0),
+        balance=100.0,
+    )
+    escrow: EscrowSession[dict[str, Any]] = EscrowSession(wallet, validator_fn=validate_result)
+
+    try:
+        out = await escrow.run(
+            job=expensive_compute,
+            amount=0.25,
+            currency="USDC",
+            recipient="0xComputeProvider",
+            domain="compute.example.com",
+            memo="summarize-doc",
+        )
+        print("Job OK:", out)
+        print("Escrow state:", escrow.record.state if escrow.record else None)
+        if escrow.record and escrow.record.release_result:
+            print("Released tx:", escrow.record.release_result.tx_hash)
+    except EscrowValidationError as exc:
+        print("Validation failed, refunded:", exc)
+
+    # Failure path demo
+    bad: EscrowSession[dict[str, Any]] = EscrowSession(
+        wallet,
+        validator_fn=lambda r: r.get("status") == "ok",
+    )
+    try:
+        await bad.run(
+            job=lambda: {"status": "error"},
+            amount=0.1,
+            currency="USDC",
+            recipient="0xComputeProvider",
+        )
+    except EscrowValidationError:
+        print("Bad job refunded, state:", bad.record.state if bad.record else None)
+
+    await wallet.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())