> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscore.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/reputation/{address}

> Look up the cached reputation profile for any wallet address.

## Request

### Headers

| Header      | Required | Description  |
| ----------- | -------- | ------------ |
| `X-API-Key` | Yes      | Your API key |

### Path parameters

| Parameter | Type   | Description                                                                                                 |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `address` | string | Wallet address: EVM (`0x...` 40-hex) or Solana (base58, 32–44 chars). Network is auto-detected from format. |

### Query parameters

| Parameter | Type   | Default | Description                          |
| --------- | ------ | ------- | ------------------------------------ |
| `chain`   | string | :       | Optional. Filter to a specific chain |

When `chain` is provided, the `chains` array and `agents` array are filtered to that chain.

## Response (Pro tier)

Pro and Enterprise tiers receive the full response:

```json theme={"dark"}
{
  "subject": {
    "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
    "chains": ["base", "ethereum"]
  },
  "score": {
    "value": 68,
    "grade": "B",
    "scored_at": "2026-03-10T12:00:00Z",
    "status": "scored",
    "version": "v1"
  },
  "verification_level": "kyc_verified",
  "chains": [
    {
      "chain": "base",
      "score": {
        "value": 68,
        "grade": "B",
        "confidence": 0.85,
        "dimensions": {
          "identity": 85,
          "activity": 35,
          "capability": 70,
          "reach": 50,
          "trust": 72
        },
        "scored_at": "2026-03-10T12:00:00Z",
        "status": "scored",
        "version": "v1"
      },
      "classification": {
        "entity_type": "agent",
        "confidence": 0.92,
        "is_known": true,
        "is_known_erc8004_agent": true,
        "has_candidate_payment_activity": true,
        "has_verified_payment_activity": false,
        "reasons": ["erc8004_registered", "has_endpoints"]
      },
      "identity": {
        "ens_name": null,
        "website_url": "https://paybot.example.com",
        "github_url": null
      },
      "activity": {
        "total_candidate_transactions": 142,
        "total_verified_transactions": 0,
        "as_candidate_payer": 80,
        "as_candidate_payee": 62,
        "as_verified_payer": 0,
        "as_verified_payee": 0,
        "counterparties_count": 17,
        "active_days": 45,
        "active_months": 3,
        "first_candidate_tx_at": "2026-01-15T08:30:00Z",
        "last_candidate_tx_at": "2026-03-10T10:22:00Z",
        "first_verified_tx_at": null,
        "last_verified_tx_at": null
      },
      "evidence_summary": {
        "metadata_kind": "https",
        "has_a2a_agent_card": false,
        "website_url": "https://paybot.example.com",
        "website_reachable": true,
        "website_mentions_mcp": false,
        "website_mentions_x402": false,
        "github_url": null,
        "github_stars": null
      }
    }
  ],
  "operator_score": {
    "score": 68,
    "grade": "B",
    "agent_count": 3,
    "chains_active": ["base", "ethereum"]
  },
  "reputation": {
    "feedback_count": 150,
    "client_count": 3,
    "trust_avg": 68.5,
    "uptime_avg": 99.2,
    "activity_avg": 35.0,
    "last_feedback_at": "2026-03-28T12:00:00Z"
  },
  "agents": [
    {
      "token_id": 42,
      "chain": "base",
      "name": "PayBot",
      "score": 68,
      "grade": "B"
    }
  ],
  "data_semantics": "candidate_payment_activity_with_verified_subset",
  "caveats": [],
  "updated_at": "2026-03-10T12:00:00Z"
}
```

`operator_score` is only present when the address has operator data (i.e., owns registered agents). `reputation` is only present on paid tier when the address has agent feedback data.

## Response (Free tier)

Free tier receives a redacted response; score, grade, and entity type only. Dimensions, confidence, payment activity, reputation, identity details, and evidence are omitted.

```json theme={"dark"}
{
  "subject": {
    "address": "0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671",
    "chains": ["base", "ethereum"]
  },
  "score": {
    "value": 68,
    "grade": "B",
    "scored_at": "2026-03-10T12:00:00Z",
    "status": "scored",
    "version": "v1"
  },
  "verification_level": "none",
  "chains": [
    {
      "chain": "base",
      "score": {
        "value": 68,
        "grade": "B",
        "scored_at": "2026-03-10T12:00:00Z",
        "status": "scored",
        "version": "v1"
      },
      "classification": {
        "entity_type": "agent"
      }
    }
  ],
  "operator_score": {
    "score": 68,
    "grade": "B"
  },
  "agents": [
    {
      "token_id": 42,
      "chain": "base",
      "name": "PayBot",
      "score": 68,
      "grade": "B"
    }
  ],
  "data_semantics": "candidate_payment_activity_with_verified_subset",
  "caveats": [],
  "updated_at": "2026-03-10T12:00:00Z"
}
```

Upgrade to Pro ([pricing](https://agentscore.sh/pricing)) for full scoring details including dimensions, confidence, payment activity, reputation breakdown, and evidence.

### Top-level score

When the address is an operator (owns agents), the top-level `score` reflects the **operator score**; a tail-risk weighted average across all agents on all chains. When the address has no agents, the top-level score is the highest per-chain address score.

Per-chain scores and classification are in the `chains` array. On Pro tier, this also includes identity, activity, and evidence.

### Data semantics

The `data_semantics` field describes what kind of transaction data was used to compute the score. The current value is `candidate_payment_activity_with_verified_subset`, meaning the score is based on candidate payment transactions with a verified subset where available.

### Score status values

| Status           | Meaning                                                                           |
| ---------------- | --------------------------------------------------------------------------------- |
| `scored`         | Score is fresh (computed within 24h)                                              |
| `stale`          | Score exists but is older than 24h. Use `POST /v1/assess` for a fresh evaluation. |
| `known_unscored` | Address is indexed but has not been scored yet                                    |

### Unknown address (404)

If the address has not been indexed:

```json theme={"dark"}
{
  "error": {
    "code": "unknown_address",
    "message": "Address not yet indexed.",
    "can_assess": true
  }
}
```

Use `POST /v1/assess` to score any address on-the-fly, including unknown ones.

### Verification level

The `verification_level` field indicates how far the operator behind this address has progressed through identity verification.

| Value            | Meaning                                          |
| ---------------- | ------------------------------------------------ |
| `none`           | No verification performed                        |
| `wallet_claimed` | Operator has signed a wallet ownership challenge |
| `kyc_verified`   | Operator has completed identity verification     |

<Note>
  This endpoint is **read-only**. It returns cached data and never triggers scoring. For fresh, on-the-fly scoring, use `POST /v1/assess` (Pro tier required).
</Note>