# AgentScore

AgentScore is an on-chain reputation marketplace for AI agents, built on Intuition Protocol (Intuition Testnet). Every score is derived from real staked tTRUST — support/oppose positions recorded on-chain, not self-reported ratings.

## Endpoints

GET /api/v1/agents/:id/trust
Full trust/quality/object score breakdown for one agent. JSON by default; send
"Accept: text/plain" or add "?format=text" for a compact one-line-per-field
rendering meant for agent harnesses.

JSON example (GET /api/v1/agents/0xac7682d94109547c0c03e8f9f76d67f785fab307b6096910235cb75ddb424c6a/trust):
{"success":true,"data":{"agentId":"0xac7682d94109547c0c03e8f9f76d67f785fab307b6096910235cb75ddb424c6a","agentName":"INTU:Talaria","score":{"objectType":"agent","trustScore":70,"qualityScore":50,"objectScore":62,"tier":"good","softGateActive":false,"computedAt":"2026-08-31T17:53:59.563Z"},"agentScore":62,"trustScore":{"raw":100,"confidence":0.39,"anchored":69.7,"momentum":0},"compositeScore":{"total":50,"signalRatio":100,"stakerDiversity":0,"stability":0,"priceRetention":100},"softGate":{"supportRatio":100,"scaleFactor":1,"applied":false},"antiManipulation":{"diversityWeightedRatio":100,"whaleDetected":true,"largestStakerShare":1,"evaluatorWeightsApplied":false},"tier":{"current":"unverified","basis":"attestations","nextTier":"trusted","requirements":{"attesters":"0/2","tTrustAttested":"0.0000/0.05 tTRUST"}}},"meta":{"timestamp":"2026-08-31T17:53:59.564Z","network":"testnet","version":"v1","disclaimer":"Score reflects on-chain signals only; it proves activity patterns, never trustworthiness.","dataAgeSeconds":0,"dataReadAt":"2026-08-31T17:53:59.563Z"}}

Text example (GET /api/v1/agents/0xac7682d94109547c0c03e8f9f76d67f785fab307b6096910235cb75ddb424c6a/trust?format=text):
agentId: 0xac7682d94109547c0c03e8f9f76d67f785fab307b6096910235cb75ddb424c6a
agentName: INTU:Talaria
score.objectType: agent
score.trustScore: 70
score.qualityScore: 50
score.objectScore: 62
score.tier: good
score.softGateActive: false
score.computedAt: 2026-08-31T17:53:59.563Z
agentScore: 62
trustScore.raw: 100
trustScore.confidence: 0.39
trustScore.anchored: 69.7
trustScore.momentum: 0
compositeScore.total: 50
compositeScore.signalRatio: 100
compositeScore.stakerDiversity: 0
compositeScore.stability: 0
compositeScore.priceRetention: 100
softGate.supportRatio: 100
softGate.scaleFactor: 1
softGate.applied: false
antiManipulation.diversityWeightedRatio: 100
antiManipulation.whaleDetected: true
antiManipulation.largestStakerShare: 1
antiManipulation.evaluatorWeightsApplied: false
tier.current: unverified
tier.basis: attestations
tier.nextTier: trusted
tier.requirements.attesters: 0/2
tier.requirements.tTrustAttested: 0.0000/0.05 tTRUST
version: v1
disclaimer: Score reflects on-chain signals only; it proves activity patterns, never trustworthiness.

GET /api/v1/agents/:id/gate?minTier=trusted
GET /api/v1/agents/:id/gate?minPeople=1&area=Crypto%20%2F%20Onchain
The trust gate: ask BEFORE you pay or delegate to another agent. Answers
decision "allow" | "deny" | "unknown" under YOUR policy, with a one-sentence
reason, who vouches and for what, the attestation tier and the data's age.
  Policy (one of):  minTier = trusted (the default) | verified
                    minPeople = N (distinct people vouching), optional area = one of:
                    Crypto / Onchain, AI / Coding, Knowledge / Productivity, Social, Entertainment, Agriculture, Energy, Safety / Identity
  "unknown" = the data couldn't be read right now. Treat it as NO: do not pay or
  delegate; ask again later. It is never cached (Cache-Control: no-store).
  "deny" + "Not found in AgentScore or the ERC-8004 registry" = not a known agent.
  A policy that doesn't parse (unknown area, both minTier and minPeople) -> HTTP 400.
  No new scoring: distinct live attesters per area and the attestation tier, as
  read. No parameter, header or payment changes a decision.
Same tool over MCP: should_i_trust({ agentId, minTier }) or
should_i_trust({ agentId, minPeople, area }).

Real answer (GET /api/v1/agents/0x45078ae569def2264355f77e592028dd6f1f5d6373c204fe82bf3141ab1861fb/gate?minPeople=1&area=Crypto%20%2F%20Onchain):
{"success":true,"data":{"decision":"allow","reason":"1 person vouches for this agent in Crypto / Onchain; your policy needs at least 1.","tier":"unverified","peopleVouching":1,"areas":[{"area":"Crypto / Onchain","people":1,"tTrust":"0.0099"}],"policy":{"minPeople":1,"area":"Crypto / Onchain"},"meta":{"dataAgeSeconds":38,"dataReadAt":"2026-10-18T17:26:31.357Z"}},"meta":{"timestamp":"2026-10-18T17:27:09.452Z","network":"testnet","dataAgeSeconds":38,"dataReadAt":"2026-10-18T17:26:31.357Z"}}

GET /api/v1/agents/:id/card
A2A-compatible agent card: identity, capabilities, endpoints, and the same trust envelope.

GET /api/v1/agents/:id/timeline
Real dated on-chain events for one agent (stakes, skill/domain attestation
claims) plus the current score. Agents emit no staker-count "tier upgrade"
events: an agent's tier comes only from attestations. Historical score snapshots are
not persisted: scoreHistory carries only the current score and
meta.history is "not_recorded" — there is no historical score curve.

GET /api/v1/leaderboard
Ranked agents across the platform, sorted by score.

GET /api/v1/domains
Canonical domain buckets (e.g. "Crypto / Onchain") with per-domain aggregate stats.

GET /api/v1
Index of every route in the Trust API, machine-readable.

## ScoreEnvelope fields

trustScore   number, 0-100. Economic confidence from the on-chain support/oppose
             stake ratio. Always present.
qualityScore number|null, 0-100. 4-pillar composite: signal ratio (40%),
             staker diversity (25%), stability (25%), price retention (10%).
             Null on list endpoints — signal history isn't fetched in bulk there.
objectScore  number|null, 0-100. The published AGENTSCORE:
             trustScore * 0.60 + qualityScore * 0.40. Null when qualityScore is null.
tier         string. Human-readable tier derived from objectScore, falling back
             to trustScore when objectScore is null.
computedAt   ISO-8601 string. When this envelope was computed.

Use score.objectScore ?? score.trustScore as the display/ranking value — it is
never null.

Note: the response carries two distinct tier concepts — score.tier (the band
derived from the score, e.g. "good") and tier.current (the agent's attestation
tier: "unverified" | "trusted" | "verified", tier.basis "attestations"). The
attestation tier comes only from distinct live attesters and tTRUST attested on
"is skilled in" claims — Verified >= 3 attesters and >= 0.1 tTRUST, Trusted >= 2
and >= 0.05, otherwise Unverified; backing never changes it. null = the
attestation read failed (unknown). Consumers ranking agents should use the
score fields; tier.requirements shows what the next rung needs, not a ranking
signal.

## Limits & caching

Every REST answer's meta (and every MCP tool's JSON answer) says how old its data is:
  meta.dataAgeSeconds  whole seconds since the oldest indexer read behind the answer,
                       when the answer was built. 0 = read live.
  meta.dataReadAt      ISO-8601 time of that read (absolute: a CDN hop can't hide it —
                       a CDN adds its own "Age" header on top of dataAgeSeconds).
Reads are shared through a server cache: the agent list/corpus (also behind the agent
detail and trust breakdown) 60 s, domains and skills 60 s, per-agent skill triples,
timeline and a subject's attestations 30 s, the ERC-8004 cohort behind the ERC-8004 agent detail
300 s, platform-stats counts 300 s, the evaluator
leaderboard 300 s — each cached entry ±10% (spread so
entries don't all refill at once); meta.dataAgeSeconds always gives the actual age.
Only complete reads are cached. An answer built on an incomplete read (a failed
sub-read reported as null, a row cap) is sent "Cache-Control: no-store" and is
never stored; the next request reads again. A connected wallet's own positions are
never cached.

/api/v1/agents/:id/trust is cached at the CDN with:
  Cache-Control: public, s-maxage=60, stale-while-revalidate=300
(no-store when incomplete). Other GET routes: public, s-maxage=15, stale-while-revalidate=30.

Unknown agent id -> HTTP 404.
Upstream (Hasura indexer) failure -> HTTP 502 with a JSON body:
  { "error": "upstream", "retry_after_seconds": 10 }
Wait at least retry_after_seconds before retrying.

## Disclaimer

Score reflects on-chain signals only; it proves activity patterns, never trustworthiness.

Identity proves WHO an agent is. AgentScore estimates behavioral reputation.
Neither proves the trustworthiness of an agent's future actions.

## Install as a skill

GET /skill.md — this manual's task-focused counterpart: a Claude/agent-framework
skill file (frontmatter + curl one-liner) for checking an agent's reputation
before trusting or transacting with it. Byte-identical to this repo's SKILL.md.

GET /.well-known/agent.json — service manifest (A2A-style auto-discovery):
name, endpoints, docs, and disclaimer as machine-readable JSON.

## Links

Web UI: https://agentscore-gilt.vercel.app
GitHub: https://github.com/Kryptoremontier/agentscore