Skip to main content
POST
/
v1
/
assess
POST /v1/assess
curl --request POST \
  --url https://api.agentscore.sh/v1/assess
This endpoint requires a paid plan ($49/mo). Free tier requests receive HTTP 402.

​
Request

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour API key (paid or enterprise tier)
Content-TypeYesapplication/json

​
Body

{
  "chain": "base",
  "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
  "refresh": false,
  "policy": {
    "min_grade": "B",
    "min_score": 50,
    "require_verified_payment_activity": false
  }
}
FieldTypeRequiredDescription
chainstringNoChain (default: base)
addressstringYesEVM wallet address
refreshbooleanNoForce score recomputation even if cached
policyobjectNoPolicy rules for allow/deny decision
policy.min_gradestringNoMinimum grade (A, B, C, D, F)
policy.min_scorenumberNoMinimum score (0-100)
policy.require_verified_payment_activitybooleanNoRequire verified payment activity

​
Response

The response includes all fields from GET /v1/reputation/{address} plus decision fields: 
{
  "subject": { "chain": "base", "address": "0x..." },
  "classification": { "..." : "..." },
  "score": {
    "status": "scored",
    "value": 76,
    "grade": "A",
    "confidence": 0.85,
    "dimensions": { "identity": 88, "activity": 40, "capability": 80, "reach": 55, "trust": 75 },
    "scored_at": "2026-03-12T14:30:00Z",
    "version": "v2"
  },
  "identity": { "..." : "..." },
  "activity": { "..." : "..." },
  "evidence_summary": { "..." : "..." },
  "decision": "allow",
  "decision_reasons": [],
  "on_the_fly": true,
  "data_semantics": "candidate_payment_activity_with_verified_subset",
  "caveats": [],
  "updated_at": "2026-03-12T14:30:00Z"
}

​
Decision values

ValueMeaning
allowAll policy rules passed, or no policy was specified
denyOne or more policy rules failed

​
Decision reasons

When all policy checks pass, decision_reasons is an empty array. When a check fails, reasons are human-readable strings:
ScenarioExample reason
Grade below minimum"Grade C is below minimum B"
Score below minimum"Score 42 is below minimum 50"
No verified payments"No verified payment activity"

​
No policy provided

When you omit the policy field, the endpoint returns decision: "allow" with decision_reasons: ["no_policy_applied"]. This is useful for on-the-fly scoring without enforcement.

​
Unknown addresses

If the address is not yet in the database, /v1/assess creates a minimal entry and scores it from scratch. The response includes "on_the_fly": true.

​
Example: middleware integration

const assessment = await fetch("https://api.agentscore.sh/v1/assess", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AGENTSCORE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    address: walletAddress,
    policy: { min_grade: "C", min_score: 40 },
  }),
}).then((r) => r.json());

if (assessment.decision === "deny") {
  return res.status(403).json({
    error: "wallet_not_trusted",
    reasons: assessment.decision_reasons,
  });
}