Skip to main content

Installation

pip install agentscore-gate
Install with framework extras:
pip install agentscore-gate[fastapi]   # FastAPI / Starlette
pip install agentscore-gate[flask]     # Flask
pip install agentscore-gate[django]    # Django

FastAPI / Starlette

from fastapi import FastAPI
from agentscore_gate import AgentScoreGate

app = FastAPI()
app.add_middleware(
    AgentScoreGate,
    api_key="your-api-key",
    min_score=50,
    min_grade="B",
)

@app.get("/api/execute")
async def execute(request):
    # Only wallets with grade B+ and score 50+ reach here
    reputation = request.state.agentscore
    return {"status": "executed", "score": reputation["score"]["value"]}

Flask

from flask import Flask, g
from agentscore_gate.flask import agentscore_gate

app = Flask(__name__)
agentscore_gate(app, api_key="your-api-key", min_score=50)

@app.route("/api/execute")
def execute():
    reputation = g.agentscore
    return {"status": "executed", "score": reputation["score"]["value"]}

Django

Add to settings.py:
MIDDLEWARE = [
    # ...
    "agentscore_gate.django.AgentScoreMiddleware",
]

AGENTSCORE_GATE = {
    "api_key": "your-api-key",
    "min_score": 50,
    "min_grade": "B",
}
Access data in views:
def execute(request):
    reputation = request.agentscore
    return JsonResponse({"status": "executed", "score": reputation["score"]["value"]})

How it works

  1. Extracts the wallet address from the X-Wallet-Address request header
  2. Calls POST /v1/assess with your policy
  3. If decision is "allow", passes the request through with reputation data attached
  4. If decision is "deny", returns 403 Forbidden with reason codes

Configuration

All three adapters accept the same options:
ParameterTypeDefaultDescription
api_keystrrequiredAPI key from agentscore.sh
min_scoreintNoneMinimum score (0–100)
min_gradestrNoneMinimum grade (A–F)
require_verified_activityboolNoneRequire verified payment activity
fail_openboolFalseAllow requests when API is unreachable
cache_secondsint300Cache TTL for results
base_urlstrhttps://api.agentscore.shAPI base URL
extract_addresscallableReads X-Wallet-Address headerCustom address extractor
extract_chaincallableReturns None (defaults to base)Custom chain extractor
on_deniedcallableReturns 403 JSONCustom denial handler

Custom wallet extraction

Override the default header-based extraction:
# FastAPI
app.add_middleware(
    AgentScoreGate,
    api_key="your-api-key",
    extract_address=lambda req: req.query_params.get("wallet"),
)

# Flask
agentscore_gate(
    app,
    api_key="your-api-key",
    extract_address=lambda req: req.args.get("wallet"),
)

Fail-open vs fail-closed

By default, the middleware fails closed — if the AgentScore API is unreachable, requests are denied. Set fail_open=True to allow requests through when the API is unavailable.

Denial reason codes

CodeDescription
wallet_not_trustedWallet didn’t meet the policy threshold
missing_wallet_addressNo wallet address found in the request
api_errorAgentScore API returned an error (and fail_open is False)
payment_requiredAPI key doesn’t have access to assess endpoint