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

# Available Tools

> Complete reference for all 21 Cred Protocol MCP tools

# MCP Tools Reference

This page documents all available MCP tools for credit scoring, financial reporting, identity verification, portfolio analysis, transaction graphs, and agentic reputation.

<Info>
  All tools return **live on-chain data** and require an API key. Pass your key via the `Authorization: Bearer YOUR_API_KEY` header.
</Info>

***

## Credit Scoring

### get\_credit\_score

Get the Cred Protocol credit score for an Ethereum address or ENS name.

<ParamField path="address" type="string" required>
  Ethereum address (0x...) or ENS name (e.g., vitalik.eth)
</ParamField>

<ParamField query="include_factors" type="boolean" default="false">
  Include detailed score factors explaining the score
</ParamField>

**Score Ranges:**

* 920-1000: Excellent
* 840-919: Very Good
* 750-839: Good
* 640-749: Fair
* 300-639: Low

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/score/vitalik.eth?include_factors=true"
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://api.credprotocol.com/mcp/score/vitalik.eth",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"include_factors": True}
  )
  score_data = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.credprotocol.com/mcp/score/vitalik.eth?include_factors=true",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const scoreData = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "score": 774,
  "decile": 5,
  "range": "good",
  "model_version": "andromeda_1.0",
  "timestamp": "2026-03-31T06:21:16.423948Z",
  "factors": [
    {
      "label": "Borrowing History",
      "rating": "good",
      "description": "You have a good track record of using lending products."
    },
    {
      "label": "Wallet Composition",
      "rating": "very_good",
      "description": "You have a very_good breakdown of tokens in your account."
    }
  ],
  "source": "live"
}
```

***

### get\_credit\_scores\_batch

Get individual credit scores for multiple Ethereum addresses at once.

<ParamField body="addresses" type="array" required>
  List of Ethereum addresses or ENS names
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.credprotocol.com/mcp/score/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"addresses": ["vitalik.eth", "0x1234..."]}'
  ```

  ```python Python theme={null}
  response = httpx.post(
      "https://api.credprotocol.com/mcp/score/batch",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"addresses": ["vitalik.eth", "0x1234..."]}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "scores": [
    {
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "score": 774,
      "decile": 5,
      "range": "good"
    },
    {
      "address": "0x1234...",
      "score": 650,
      "decile": 6,
      "range": "fair"
    }
  ],
  "count": 2,
  "source": "live"
}
```

***

### get\_aggregate\_score

Get a single aggregated credit score across multiple Ethereum addresses. Useful for multi-sig wallets or portfolio-level assessments.

<ParamField query="addresses" type="string" required>
  Comma-separated Ethereum addresses or ENS names
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/score/aggregate?addresses=vitalik.eth,0x1234..."
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/score/aggregate",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"addresses": "vitalik.eth,0x1234..."}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8da6bf2...,0x1234...",
  "score": 760,
  "model_version": "andromeda_1.0",
  "source": "live"
}
```

***

## Financial Reporting

### get\_financial\_summary

Get a comprehensive financial summary for an Ethereum address. Includes assets, DeFi positions, credit events, and global percentile rankings.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

**Includes:**

* Asset values (total assets, collateral, debt, stablecoins)
* Activity metrics (transactions, transfers, NFTs)
* DeFi positions (loans, collateral deposits)
* Credit events (liquidations, defaults, repayments)
* Identity attestations

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/summary/vitalik.eth"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/summary/vitalik.eth",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  summary = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "report": {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "timestamp": "2026-03-31T06:21:16Z",
    "first_transaction": {
      "timestamp": "2015-08-07T00:00:00Z",
      "age_human": "10 years ago"
    },
    "summary": {
      "net_worth_usd": 2450000.50,
      "total_asset_usd": 2500000.00,
      "total_collateral_usd": 500000.00,
      "total_debt_usd": 50000.00,
      "count_transactions": 15230,
      "count_nfts": 142,
      "count_active_loans": 2,
      "count_liquidations": 0
    }
  },
  "source": "live"
}
```

***

### get\_comprehensive\_report

Get the most detailed multi-chain credit report, including per-chain breakdowns with balances, transactions, NFTs, DeFi positions, and credit events.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/report/vitalik.eth"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/report/vitalik.eth",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  report = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "report": {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "timestamp": "2026-03-31T06:21:16Z",
    "first_transaction": {
      "timestamp": "2015-08-07T00:00:00Z",
      "age_human": "10 years ago"
    },
    "summary": {
      "net_worth_usd": 2450000.50,
      "total_asset_usd": 2500000.00,
      "total_collateral_usd": 500000.00,
      "total_debt_usd": 50000.00,
      "count_transactions": 15230,
      "count_nfts": 142,
      "count_active_loans": 2,
      "count_liquidations": 0
    },
    "global_summary_stats": { "..." : "..." },
    "global_percentiles": {
      "net_worth_percentile": 99,
      "transaction_count_percentile": 98,
      "nft_count_percentile": 95
    }
  },
  "source": "live"
}
```

**Performance:** Response time 5-10 seconds (aggregates data across multiple chains). Results cached for 5 minutes.

***

### get\_summary\_report

Get aggregated metrics across all chains without per-chain breakdowns. Lighter than the comprehensive report.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/report/vitalik.eth/summary"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/report/vitalik.eth/summary",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "summary": {
    "net_worth_usd": 2450000.50,
    "total_asset_usd": 2500000.00,
    "count_transactions": 15230,
    "count_nfts": 142
  },
  "source": "live"
}
```

***

### get\_chain\_report

Get a detailed credit report for a single blockchain including balances, transactions, NFTs, DeFi positions, and credit events.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<ParamField path="chain_id" type="integer" required>
  Blockchain network ID (see [Supported Chains](#supported-chains))
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/report/vitalik.eth/chain/1"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/report/vitalik.eth/chain/1",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

***

### get\_chain\_summary

Get aggregated metrics for a single blockchain without detailed balance/transaction lists.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<ParamField path="chain_id" type="integer" required>
  Blockchain network ID (see [Supported Chains](#supported-chains))
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/report/vitalik.eth/chain/8453/summary"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/report/vitalik.eth/chain/8453/summary",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

***

## Portfolio Value

### get\_portfolio\_value

Get the total USD value of all assets across all supported blockchains.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/portfolio/vitalik.eth"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/portfolio/vitalik.eth",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  portfolio = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "total_asset_usd": 2500000.00,
  "timestamp": "2026-03-31T06:21:16Z",
  "source": "live"
}
```

***

### get\_chain\_portfolio\_value

Get the portfolio value on a specific blockchain.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<ParamField path="chain_id" type="integer" required>
  Blockchain network ID (see [Supported Chains](#supported-chains))
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  # Get Ethereum portfolio
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/portfolio/vitalik.eth/chain/1"

  # Get Base portfolio
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/portfolio/vitalik.eth/chain/8453"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/portfolio/vitalik.eth/chain/1",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  eth_portfolio = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain_id": 1,
  "chain_name": "Ethereum",
  "total_asset_usd": 1950000.25,
  "timestamp": "2026-03-31T06:21:16Z",
  "source": "live"
}
```

***

### get\_portfolio\_composition

Get portfolio value broken down by asset type (tokens, DeFi positions, stablecoins, collateral, debt).

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/portfolio/vitalik.eth/composition"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/portfolio/vitalik.eth/composition",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "total_asset_usd": 2500000.00,
  "breakdown": {
    "tokens": 1800000.00,
    "stablecoins": 400000.00,
    "defi_positions": 250000.00,
    "collateral": 500000.00,
    "debt": -50000.00
  },
  "source": "live"
}
```

***

## Identity Verification

### get\_identity\_attestations

Get verified identity attestations for an Ethereum address.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

**Attestation Types:**

* ENS Name - Ethereum Name Service domain ownership
* Basename - Base network name service (username.base.eth)
* Gitcoin Passport - Humanity verification (score ≥ 20)
* POAPs - Proof of Attendance Protocol tokens
* Worldcoin - Verified human
* BrightID - Social verification

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/identity/vitalik.eth"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/identity/vitalik.eth",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  identity = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "attestations": [
    "ENS Name",
    "Gitcoin Passport",
    "Proof of Humanity"
  ],
  "count": 3,
  "source": "live"
}
```

***

### get\_sybil\_score

Get a sybil detection score evaluating whether an address is a unique human or a sybil (duplicate/bot) account.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/identity/vitalik.eth/sybil"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/identity/vitalik.eth/sybil",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  sybil = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "timestamp": "2026-03-31T06:21:16Z",
  "sybil_score": 12,
  "risk_level": "low",
  "indicators": {
    "count_unique_counterparties": 245,
    "count_unique_contracts_interacted": 89,
    "total_gas_spent_eth": 3.45,
    "funding_source_address": "0x...",
    "transaction_time_entropy": 0.92,
    "identity_attestations": 5,
    "wallet_age_days": 3200,
    "transaction_count": 15230
  },
  "source": "live"
}
```

**Risk Levels:**

* `low` (0-25): Likely a unique human
* `medium` (26-50): Some suspicious indicators
* `high` (51-75): Multiple sybil indicators
* `critical` (76-100): Very likely a sybil/bot

***

## Transaction Graph

### get\_transaction\_graph

Get a transaction graph showing ERC-20 token transfer relationships as nodes and edges. Useful for visualizing transaction flow, identifying counterparties, and analyzing wallet activity patterns.

<ParamField path="address" type="string" required>
  Ethereum address or ENS name
</ParamField>

<ParamField query="chain_id" type="integer" default="1">
  Blockchain network ID (default: Ethereum)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  # Ethereum transaction graph
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/graph/vitalik.eth?chain_id=1"

  # Base transaction graph
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/graph/vitalik.eth?chain_id=8453"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/graph/vitalik.eth",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"chain_id": 1}
  )
  graph = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.credprotocol.com/mcp/graph/vitalik.eth?chain_id=1",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const graph = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "nodes": [
    {"id": "0xd8dA6BF2...", "label": "0xd8dA6BF2...", "group": "wallet"},
    {"id": "USDC", "label": "USDC", "group": "token"},
    {"id": "0xAb5801a7...", "label": "0xAb5801a7...", "group": "wallet"}
  ],
  "edges": [
    {"from": "0xd8dA6BF2...", "to": "USDC", "label": "SENT"},
    {"from": "USDC", "to": "0xAb5801a7...", "label": "RECEIVED"}
  ],
  "total_transactions": 150,
  "chain_id": 1,
  "chain_name": "Ethereum Mainnet",
  "address": "0xd8dA6BF2...",
  "source": "live"
}
```

**Graph structure:** Tripartite graph (wallet → token → wallet) built from historical ERC-20 transfers.

**Performance:** Response time 2-5 seconds on first request, \~50-100ms on cached requests. Cached for 10 minutes.

***

## Agentic Reputation (ERC-8004)

<Info>
  [ERC-8004](https://github.com/credprotocol/ERCs/blob/master/ERCS/erc-8004.md) defines a standard for registering AI agent identities on-chain as ERC-721 tokens. Each agent has an owner address and metadata (name, description, image) resolved from its tokenURI. The registry lives on Base (chain ID 8453).
</Info>

### get\_agent\_count

Get the total number of AI agents registered in the ERC-8004 Identity Registry on Base.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/agents/count"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/agents/count",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "total": 42,
  "source": "live"
}
```

***

### list\_agents

Get a paginated list of AI agents from the ERC-8004 Identity Registry.

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page (max: 100)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/agents?page=1&limit=10"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/agents",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"page": 1, "limit": 10}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "agents": [
    {
      "agent_id": 1,
      "owner": "0xc38947DA1EB4466D17d5C6c34a0f26Dbe803d107",
      "metadata": {
        "name": "Cred Protocol Validator",
        "description": "ERC-8004 reputation validator for on-chain credit scoring",
        "image": "ipfs://QmExample..."
      }
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10,
  "source": "live"
}
```

***

### search\_agents

Search for AI agents by name or description using case-insensitive substring matching.

<ParamField query="q" type="string" required>
  Search query — matches against agent name or description
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page (max: 100)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/agents/search?q=lending&limit=5"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/agents/search",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"q": "lending", "page": 1, "limit": 5}
  )
  agents = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.credprotocol.com/mcp/agents/search?q=lending&limit=5",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const agents = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "agents": [
    {
      "agent_id": 42,
      "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f32345",
      "metadata": {
        "name": "DeFi Lending Advisor",
        "description": "An AI agent that evaluates lending opportunities across DeFi protocols",
        "image": "ipfs://QmExample..."
      }
    }
  ],
  "total_results": 1,
  "query": "lending",
  "page": 1,
  "limit": 5,
  "source": "live"
}
```

**Performance:** Results served from a cached agent index (refreshed every 12 hours). Response time typically under 1 second.

***

### get\_agent

Get info for a specific AI agent by its ERC-8004 ID.

<ParamField path="agent_id" type="integer" required>
  ERC-8004 agent ID (starts at 1)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/agents/1"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/agents/1",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "agent_id": 1,
  "owner": "0xc38947DA1EB4466D17d5C6c34a0f26Dbe803d107",
  "metadata": {
    "name": "Cred Protocol Validator",
    "description": "ERC-8004 reputation validator for on-chain credit scoring",
    "image": "ipfs://QmExample..."
  },
  "source": "live"
}
```

***

### submit\_agent\_reputation

Submit ERC-8004 reputation feedback for an AI agent. Computes credit score, sybil risk, and identity attestations, then submits results as on-chain feedback to the Reputation Registry on Base.

<ParamField path="agent_id" type="integer" required>
  ERC-8004 agent ID from Identity Registry (>= 1)
</ParamField>

<ParamField body="address" type="string" required>
  Ethereum address to score for this agent
</ParamField>

<ParamField body="tags" type="array">
  Feedback tags to submit. Options: `creditScore`, `sybilRisk`, `identityCount`. Default: all three.
</ParamField>

**Costs 10 Cred Units.**

<Note>
  The submission is asynchronous. This endpoint returns immediately with a tracking ID. Use `get_reputation_status` to poll for completion.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    "https://api.credprotocol.com/mcp/agents/1/reputation" \
    -d '{"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD1e"}'
  ```

  ```python Python theme={null}
  response = httpx.post(
      "https://api.credprotocol.com/mcp/agents/1/reputation",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD1e",
          "tags": ["creditScore", "sybilRisk"]
      }
  )
  ```
</CodeGroup>

**Response (202 Accepted):**

```json theme={null}
{
  "submission_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": 1,
  "status": "pending",
  "estimated_completion_seconds": 45,
  "status_url": "/api/v2/agents/1/reputation/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": ["creditScore", "sybilRisk", "identityCount"],
  "source": "live"
}
```

***

### get\_agent\_reputation

Read the on-chain reputation summary for an AI agent from the ERC-8004 Reputation Registry.

<ParamField path="agent_id" type="integer" required>
  ERC-8004 agent ID (>= 1)
</ParamField>

**Costs 1 Cred Unit.**

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/agents/1/reputation"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/agents/1/reputation",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "agent_id": 1,
  "summaries": [
    {
      "tag1": "credprotocol.com",
      "tag2": "creditScore",
      "count": 15,
      "summary_value": 745.5,
      "summary_value_decimals": 1
    },
    {
      "tag1": "credprotocol.com",
      "tag2": "sybilRisk",
      "count": 15,
      "summary_value": 28.3,
      "summary_value_decimals": 1
    }
  ],
  "source": "live"
}
```

***

### get\_reputation\_status

Check the status of an on-chain reputation submission.

<ParamField path="agent_id" type="integer" required>
  ERC-8004 agent ID
</ParamField>

<ParamField path="submission_id" type="string" required>
  Submission UUID returned by `submit_agent_reputation`
</ParamField>

**Status values:** `pending` → `computing` → `submitting` → `confirmed` (or `failed`)

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.credprotocol.com/mcp/agents/1/reputation/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.credprotocol.com/mcp/agents/1/reputation/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "submission_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": 1,
  "status": "confirmed",
  "scores": {
    "credit_score": 780,
    "sybil_score": 22,
    "identity_count": 4
  },
  "transactions": [
    {
      "tag1": "credprotocol.com",
      "transaction_hash": "0xabc123...",
      "block_number": 12345678,
      "gas_used": 145000
    }
  ],
  "feedback_uri": "https://api.credprotocol.com/api/v2/agents/1/reputation/feedback/a1b2c3d4...",
  "source": "live"
}
```

***

## Supported Chains

| Chain     | ID     |
| --------- | ------ |
| Ethereum  | 1      |
| Optimism  | 10     |
| BSC       | 56     |
| Polygon   | 137    |
| Base      | 8453   |
| Arbitrum  | 42161  |
| Celo      | 42220  |
| Avalanche | 43114  |
| Scroll    | 534352 |
| Linea     | 59144  |

***

## Error Handling

All endpoints return consistent error responses:

```json theme={null}
{
  "error": "Invalid Ethereum address format: abc123",
  "status_code": 400
}
```

Common error codes:

* `400` - Invalid request (bad address format, missing parameters)
* `401` - Authentication required (missing or invalid API key)
* `404` - Resource not found (agent doesn't exist)
* `503` - API connection failed
* `504` - Request timeout