Skip to main content

​
MCP Tools Reference

This page documents all available MCP tools for credit scoring, financial reporting, identity verification, portfolio analysis, transaction graphs, and agentic reputation.
All tools return live on-chain data and require an API key. Pass your key via the Authorization: Bearer YOUR_API_KEY header.

​
Credit Scoring

​
get_credit_score

Get the Cred Protocol credit score for an Ethereum address or ENS name.
​
address
string
required
Ethereum address (0x…) or ENS name (e.g., vitalik.eth)
​
include_factors
boolean
default:"false"
Include detailed score factors explaining the score
Score Ranges:
  • 920-1000: Excellent
  • 840-919: Very Good
  • 750-839: Good
  • 640-749: Fair
  • 300-639: Low
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/score/vitalik.eth?include_factors=true"
Response: 
{
  "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.
​
addresses
array
required
List of Ethereum addresses or ENS names
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..."]}'
Response: 
{
  "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.
​
addresses
string
required
Comma-separated Ethereum addresses or ENS names
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/score/aggregate?addresses=vitalik.eth,0x1234..."
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
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
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/summary/vitalik.eth"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/report/vitalik.eth"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/report/vitalik.eth/summary"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
​
chain_id
integer
required
Blockchain network ID (see Supported Chains)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/report/vitalik.eth/chain/1"

​
get_chain_summary

Get aggregated metrics for a single blockchain without detailed balance/transaction lists.
​
address
string
required
Ethereum address or ENS name
​
chain_id
integer
required
Blockchain network ID (see Supported Chains)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/report/vitalik.eth/chain/8453/summary"

​
Portfolio Value

​
get_portfolio_value

Get the total USD value of all assets across all supported blockchains.
​
address
string
required
Ethereum address or ENS name
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/portfolio/vitalik.eth"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
​
chain_id
integer
required
Blockchain network ID (see Supported Chains)
# 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"
Response: 
{
  "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).
​
address
string
required
Ethereum address or ENS name
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/portfolio/vitalik.eth/composition"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
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
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/identity/vitalik.eth"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/identity/vitalik.eth/sybil"
Response: 
{
  "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.
​
address
string
required
Ethereum address or ENS name
​
chain_id
integer
default:"1"
Blockchain network ID (default: Ethereum)
# 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"
Response: 
{
  "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)

ERC-8004 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).

​
get_agent_count

Get the total number of AI agents registered in the ERC-8004 Identity Registry on Base. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/agents/count"
Response: 
{
  "total": 42,
  "source": "live"
}

​
list_agents

Get a paginated list of AI agents from the ERC-8004 Identity Registry.
​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"20"
Results per page (max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/agents?page=1&limit=10"
Response: 
{
  "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.
​
q
string
required
Search query — matches against agent name or description
​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"20"
Results per page (max: 100)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/agents/search?q=lending&limit=5"
Response: 
{
  "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.
​
agent_id
integer
required
ERC-8004 agent ID (starts at 1)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/agents/1"
Response: 
{
  "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.
​
agent_id
integer
required
ERC-8004 agent ID from Identity Registry (>= 1)
​
address
string
required
Ethereum address to score for this agent
​
tags
array
Feedback tags to submit. Options: creditScore, sybilRisk, identityCount. Default: all three.
Costs 10 Cred Units.
The submission is asynchronous. This endpoint returns immediately with a tracking ID. Use get_reputation_status to poll for completion.
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"}'
Response (202 Accepted): 
{
  "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.
​
agent_id
integer
required
ERC-8004 agent ID (>= 1)
Costs 1 Cred Unit. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/agents/1/reputation"
Response: 
{
  "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.
​
agent_id
integer
required
ERC-8004 agent ID
​
submission_id
string
required
Submission UUID returned by submit_agent_reputation
Status values: pending → computing → submitting → confirmed (or failed) 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/mcp/agents/1/reputation/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Response: 
{
  "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

ChainID
Ethereum1
Optimism10
BSC56
Polygon137
Base8453
Arbitrum42161
Celo42220
Avalanche43114
Scroll534352
Linea59144

​
Error Handling

All endpoints return consistent error responses: 
{
  "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