Skip to main content

​
Overview

AgentScore does not just return a score — it returns a decision. The decision object tells you whether a wallet should be allowed to proceed, along with machine-readable reason codes explaining why. This is the highest-value primitive in the API. Instead of writing your own threshold logic, pass your policy parameters and get back an enforceable result.

​
How decisions work

When you request view=full with policy parameters, AgentScore evaluates the wallet against your policy and returns: 
{
  "decision": {
    "allow": true,
    "reasons": [
      "sufficient_transaction_history",
      "recent_activity",
      "counterparty_diversity_ok"
    ],
    "policy": {
      "min_grade": "B",
      "min_transactions": 5
    }
  }
}
  • allow — true if the wallet passes all policy checks, false otherwise
  • reasons — Array of reason codes explaining the decision
  • policy — Echo of the policy inputs used for this decision

​
Policy parameters

Pass these as query parameters on the reputation endpoint:
ParameterTypeDescription
min_gradestringMinimum acceptable grade (A, B, C, D, F)
min_transactionsnumberMinimum transaction count required
If no policy parameters are provided, AgentScore applies a default policy (grade C or above, at least 1 transaction).

​
Decision logic

The decision is computed deterministically:
  1. Compute the wallet’s score and grade
  2. Check if the grade meets or exceeds min_grade
  3. Check if total transactions meet or exceed min_transactions
  4. If all checks pass, allow: true with positive reason codes
  5. If any check fails, allow: false with specific failure reason codes

​
Reason codes

​
Positive (allow = true)

CodeMeaning
sufficient_transaction_historyTransaction count meets the threshold
recent_activityWallet was active within the recency window
counterparty_diversity_okWallet interacts with diverse counterparties

​
Negative (allow = false)

CodeMeaning
insufficient_activityToo few transactions
low_diversityToo few unique counterparties
stale_activityNo recent transactions
grade_below_thresholdGrade is below the requested min_grade
below_min_transactionsTransaction count is below min_transactions

​
Integration pattern

The recommended pattern is a simple gate at the entry point of your service: 
async function gateAgent(walletAddress) {
  const rep = await fetch(
    `https://api.agentscore.sh/v1/reputation/${walletAddress}?view=full&min_grade=B&min_transactions=5`,
    { headers: { "X-API-Key": process.env.AGENTSCORE_API_KEY } }
  ).then((r) => r.json());

  if (!rep.decision.allow) {
    return {
      allowed: false,
      reasons: rep.decision.reasons,
      grade: rep.grade,
      score: rep.score,
    };
  }

  return { allowed: true };
}

​
Choosing a policy

Use caseSuggested policyRationale
Low-stakes browsingmin_grade=DAllow most wallets, filter obvious spam
Standard API accessmin_grade=C, min_transactions=3Balanced trust requirement
Financial transactionsmin_grade=B, min_transactions=10Higher bar for money movement
High-value operationsmin_grade=A, min_transactions=50Only well-established wallets

​
Free tier preview

Free-tier responses include a preview object with non-binding hints: 
{
  "preview": {
    "allow_hint": true,
    "grade_hint": "B"
  }
}
This is informational only. For enforceable decisions with reason codes, use a paid API key with view=full.

​
Batch decisions

The batch endpoint applies the same policy to all addresses in a single request, returning a decision for each: 
{
  "results": [
    { "address": "0xabc...", "decision": { "allow": true, "reasons": ["..."] } },
    { "address": "0xdef...", "decision": { "allow": false, "reasons": ["..."] } }
  ]
}