Skip to main content
GET
/
v1
/
reputation
/
{address}
Reputation
curl --request GET \
  --url https://api.agentscore.sh/v1/reputation/{address}
{
  "address": "<string>",
  "model_version": "<string>",
  "computed_at": "<string>",
  "data_through": {},
  "score": 123,
  "grade": "<string>",
  "preview": {},
  "highlights": {},
  "cache": {},
  "decision": {},
  "factors": {},
  "metrics": {},
  "identity": {},
  "attestation": {},
  "billing": {}
}

​
Overview

The canonical trust lookup endpoint. Given an EVM wallet address, returns a reputation score, grade, and (on paid tiers) an allow/deny decision with reason codes. This is the primary endpoint for integrating AgentScore into gateways, middleware, and agent workflows.

​
Path parameters

​
address
string
required
EVM wallet address (0x-prefixed, 42 characters).

​
Query parameters

​
view
string
default:"summary"
Response detail level. summary (free) or full (paid).
​
min_grade
string
Minimum acceptable grade for the decision (e.g., B). Paid tier only. Used to compute the decision.allow field.
​
min_transactions
number
Minimum transaction count for the decision (e.g., 5). Paid tier only. Used to compute the decision.allow field.

​
Authentication

Requires X-API-Key header. See Authentication.

​
Summary response (free tier)

The default response for free-tier API keys. 
{
  "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
  "model_version": "v1",
  "computed_at": "2026-03-08T17:20:00Z",
  "data_through": {
    "chain": "base",
    "block": 12345678
  },
  "score": 82.4,
  "grade": "B",
  "preview": {
    "allow_hint": true,
    "grade_hint": "B"
  },
  "highlights": {
    "total_transactions": 142,
    "unique_counterparties": 17,
    "total_volume_usdc": 38.75,
    "last_seen": "2026-03-08T15:42:11Z",
    "tenure_days": 45.2
  },
  "cache": {
    "ttl_seconds": 300
  }
}

​
Summary fields

​
address
string
required
The queried wallet address.
​
model_version
string
required
Scoring model version used to compute this result.
​
computed_at
string
required
ISO 8601 timestamp of when the score was computed.
​
data_through
object
required
Freshness metadata indicating the chain and latest block included in the computation.
​
score
number
required
Composite trust score from 0 to 100.
​
grade
string
required
Letter grade: A (90-100), B (75-89), C (50-74), D (25-49), F (0-24).
​
preview
object
required
Decision preview for free-tier consumers. allow_hint indicates whether the wallet would pass a default policy. Not a binding decision — upgrade to paid for enforceable decisions.
​
highlights
object
required
Key metrics: total_transactions, unique_counterparties, total_volume_usdc, last_seen, tenure_days.
​
cache
object
required
Cache metadata. ttl_seconds indicates how long this result can be safely cached.

​
Full response (paid tier)

Pass ?view=full with a paid API key to get the complete response including decisioning, factor breakdowns, and identity data. 
curl -H "X-API-Key: sk_live_abc123..." \
  "https://api.agentscore.sh/v1/reputation/0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671?view=full&min_grade=B&min_transactions=5"
Response
{
  "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
  "model_version": "v1",
  "computed_at": "2026-03-08T17:20:00Z",
  "data_through": {
    "chain": "base",
    "block": 12345678
  },
  "score": 82.4,
  "grade": "B",
  "decision": {
    "allow": true,
    "reasons": [
      "sufficient_transaction_history",
      "recent_activity",
      "counterparty_diversity_ok"
    ],
    "policy": {
      "min_grade": "B",
      "min_transactions": 5
    }
  },
  "factors": {
    "volume": {
      "score": 74.2,
      "weight": 0.2,
      "raw": {
        "transactions": 142,
        "window_days": 30
      }
    },
    "diversity": {
      "score": 81.0,
      "weight": 0.25,
      "raw": {
        "unique_counterparties": 17,
        "window_days": 30
      }
    },
    "consistency": {
      "score": 78.5,
      "weight": 0.2,
      "raw": {
        "active_months": 2,
        "distinct_days": 18
      }
    },
    "recency": {
      "score": 95.0,
      "weight": 0.2,
      "raw": {
        "days_since_last_activity": 0.1
      }
    },
    "tenure": {
      "score": 72.3,
      "weight": 0.15,
      "raw": {
        "tenure_days": 45.2
      }
    }
  },
  "metrics": {
    "total_transactions": 142,
    "unique_counterparties": 17,
    "total_volume_usdc": 38.75,
    "first_seen": "2026-01-23T11:02:00Z",
    "last_seen": "2026-03-08T15:42:11Z",
    "avg_latency_ms": 210
  },
  "identity": {
    "ens_name": null,
    "registered_agent": true,
    "chains_registered": ["base"],
    "endpoint_status": "healthy",
    "github_repo": null
  },
  "attestation": {
    "status": "none"
  },
  "cache": {
    "ttl_seconds": 60
  },
  "billing": {
    "tier": "paid"
  }
}

​
Additional full-response fields

​
decision
object
required
The allow/deny decision. Contains allow (boolean), reasons (array of machine-readable reason codes), and policy (echoed policy inputs).
​
factors
object
required
Breakdown of individual scoring factors. Each factor includes score (0-100), weight, and raw input data.
​
metrics
object
required
Detailed wallet metrics including first_seen, last_seen, total_volume_usdc, and avg_latency_ms.
​
identity
object | null
required
Identity metadata if available: ens_name, registered_agent, chains_registered, endpoint_status, github_repo.
​
attestation
object
required
Attestation status. Currently returns "none" — future versions will support on-chain attestations.
​
billing
object
required
Billing metadata indicating the tier used for this request.

​
Decision reason codes

CodeMeaning
sufficient_transaction_historyWallet has enough transaction volume
recent_activityWallet was active recently
counterparty_diversity_okWallet interacts with diverse counterparties
insufficient_activityToo few transactions
low_diversityInteracts with too few counterparties
stale_activityNo recent transactions
grade_below_thresholdScore grade is below the requested min_grade
below_min_transactionsTransaction count below min_transactions

​
Errors

StatusCodeDescription
400invalid_addressThe address is not a valid EVM address
401unauthorizedMissing or invalid API key
402payment_requiredPaid feature requested on free tier, or plan limit exceeded
404not_foundNo data available for this address
429rate_limitedToo many requests
500internal_errorUnexpected server error
503stale_dataData pipeline is behind; results may be unreliable