Skip to main content

​
1. Get an API key

Sign up at agentscore.sh to get your API key. The free tier gives you 50 requests to GET /v1/reputation (grade + score) at 1 request per second.

​
2. Look up a wallet

Make a GET request to the reputation endpoint with any wallet address; EVM (0x... hex) or Solana (base58): 
curl -H "X-API-Key: your-api-key" \
  https://api.agentscore.sh/v1/reputation/0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671

​
3. Read the response

Response abbreviated; see GET /v1/reputation for the full format. 
{
  "subject": {
    "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
    "chains": ["base"]
  },
  "score": {
    "value": 68,
    "grade": "B",
    "status": "scored"
  },
  "chains": [
    {
      "chain": "base",
      "score": { "value": 68, "grade": "B" },
      "classification": { "entity_type": "agent", "is_known_erc8004_agent": true }
    }
  ],
  "data_semantics": "candidate_payment_activity_with_verified_subset"
}
Key fields:
  • score.value: Operator-level trust score from 0 to 100
  • score.grade: Letter grade (A/B/C/D/F) for quick evaluation
  • chains[].score: Per-chain score (full dimensions on Pro tier)
  • chains[].classification: Per-chain entity type and classification

​
4. Make a trust decision (paid plan)

On a paid plan (pricing), use POST /v1/assess to get an explicit allow/deny decision: 
curl -X POST https://api.agentscore.sh/v1/assess \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
    "policy": { "require_kyc": true }
  }'
The response includes a decision field (abbreviated; see POST /v1/assess for the full format): 
{
  "decision": "allow",
  "decision_reasons": []
}

​
5. Enforce in your application

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: { require_kyc: true },
  }),
}).then((r) => r.json());

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

// Proceed with the transaction
This is a minimal raw-API integration. For production merchants, use AgentScore Commerce (Node.js) or AgentScore Commerce (Python); they ship a drop-in identity gate that auto-routes fixable compliance reasons (kyc_required, kyc_pending, kyc_failed) into a self-service verification flow (mints a session, returns verify_url + poll_secret, agent polls for a fresh operator_token), and surfaces contact_support for unfixable reasons (sanctions_flagged, age_insufficient, jurisdiction_restricted). The raw decision === "deny" example above collapses every denial into a single bare 403, which works for prototyping but loses the structured agent-recovery contract.

​
Next steps

Agent Commerce Quickstart

Merchant side: drop-in AgentScore Gate middleware, Martin Estate as the worked example.

Agent Identity Integration

Agent side: which identity header to send, handling denials, memory contract.

AgentScore SDK (TypeScript)

Official Node.js / TypeScript client.

AgentScore SDK (Python)

Official Python client with async support.

AgentScore Commerce (Node.js)

Identity middleware + payment helpers + 402 builders for Hono, Express, Fastify, Next.js, and Web Fetch.

AgentScore Commerce (Python)

Identity middleware + payment helpers + 402 builders for FastAPI, Flask, Django, AIOHTTP, and Sanic.

AgentScore Pay; MCP Server

Add trust lookups to Claude and Cursor.

API Reference

Full endpoint documentation.