Installation
FastAPI / Starlette
Flask
Django
Add tosettings.py:
How it works
- Extracts the wallet address from the
X-Wallet-Addressrequest header - Calls
POST /v1/assesswith your policy - If
decisionis"allow", passes the request through with reputation data attached - If
decisionis"deny", returns403 Forbiddenwith reason codes
Configuration
All three adapters accept the same options:| Parameter | Type | Default | Description |
|---|---|---|---|
api_key | str | required | API key from agentscore.sh |
min_score | int | None | Minimum score (0–100) |
min_grade | str | None | Minimum grade (A–F) |
require_verified_activity | bool | 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 |
extract_chain | callable | Returns None (defaults to base) | Custom chain extractor |
on_denied | callable | Returns 403 JSON | Custom denial handler |
Custom wallet extraction
Override the default header-based extraction:Fail-open vs fail-closed
By default, the middleware fails closed — if the AgentScore API is unreachable, requests are denied. Setfail_open=True to allow requests through when the API is unavailable.
Denial reason codes
| Code | Description |
|---|---|
wallet_not_trusted | Wallet didn’t meet the policy threshold |
missing_wallet_address | No wallet address found in the request |
api_error | AgentScore API returned an error (and fail_open is False) |
payment_required | API key doesn’t have access to assess endpoint |