Metadata-Version: 2.4
Name: agentscore-gate
Version: 1.0.1
Summary: Trust-gating middleware for Python web frameworks using AgentScore
Project-URL: Homepage, https://agentscore.sh
Project-URL: Repository, https://github.com/agentscore/python-gate
Project-URL: Issues, https://github.com/agentscore/python-gate/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agent,agentic-payments,agentscore,ai-agent,blockchain,django,erc-8004,fastapi,flask,gate,middleware,reputation,starlette,trust,wallet,x402
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Framework :: Django
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx<1.0.0,>=0.25.0
Provides-Extra: django
Requires-Dist: django>=4.0; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == 'flask'
Provides-Extra: starlette
Requires-Dist: starlette>=0.27.0; extra == 'starlette'
Description-Content-Type: text/markdown

# agentscore-gate

[![PyPI version](https://img.shields.io/pypi/v/agentscore-gate.svg)](https://pypi.org/project/agentscore-gate/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

ASGI middleware for trust-gating requests using [AgentScore](https://agentscore.sh). Verify AI agent wallet reputation before allowing requests through, built for the [x402](https://github.com/coinbase/x402) payment ecosystem and [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) agent registry. Works with FastAPI, Starlette, and any ASGI framework.

## Install

```bash
pip install agentscore-gate
```

## Quick Start

### FastAPI

```python
from fastapi import FastAPI
from agentscore_gate import AgentScoreGate

app = FastAPI()
app.add_middleware(AgentScoreGate, api_key="ask_...", min_score=50)

@app.get("/")
async def root():
    return {"message": "Hello, trusted agent!"}
```

### Starlette

```python
from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route
from agentscore_gate import AgentScoreGate

async def homepage(request):
    agentscore_data = request.state.agentscore
    return PlainTextResponse("Hello, trusted agent!")

app = Starlette(routes=[Route("/", homepage)])
app.add_middleware(AgentScoreGate, api_key="ask_...", min_score=50)
```

## Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | *required* | API key from [agentscore.sh](https://agentscore.sh) |
| `min_score` | `int \| None` | `None` | Minimum score (0–100) |
| `min_grade` | `str \| None` | `None` | Minimum grade (A–F) |
| `require_verified_activity` | `bool \| None` | `None` | Require verified payment activity |
| `fail_open` | `bool` | `False` | Allow requests when API is unreachable |
| `cache_seconds` | `int` | `300` | Cache TTL for results |
| `base_url` | `str` | `https://api.agentscore.sh` | API base URL |
| `extract_address` | `callable` | Reads `x-wallet-address` header | Custom address extractor |
| `on_denied` | `async callable` | Returns 403 JSON | Custom denial handler |

## How It Works

1. Extracts wallet address from request header (`x-wallet-address`)
2. Checks in-memory cache for a previous result
3. Calls AgentScore `/v1/assess` with your policy
4. Allows or blocks based on the decision
5. Attaches data to `request.state.agentscore` on allowed requests

## Documentation

- [API Reference](https://docs.agentscore.sh)
- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004)
- [x402 Protocol](https://github.com/coinbase/x402)

## License

[MIT](LICENSE)
