> ## 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.

# List Agents

> List registered agents with their owner addresses

## Overview

Returns a paginated list of agents from the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry on Base, including each agent's owner address. Use this to discover valid agent IDs for submitting reputation feedback.

<Info>
  This is a free endpoint (0 Cred Units). It reads directly from the on-chain Identity Registry contract on Base.
</Info>

## Authentication

| Method       | Header                               | Cost         |
| ------------ | ------------------------------------ | ------------ |
| API Token    | `Authorization: Bearer YOUR_API_KEY` | 0 Cred Units |
| x402 Payment | `X-PAYMENT: <signed_payment>`        | Free         |

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (must be >= 1)
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of agents per page (1-100)
</ParamField>

## Response

<ResponseField name="agents" type="array">
  Array of agent objects on this page
</ResponseField>

<ResponseField name="agents[].agent_id" type="integer">
  The ERC-8004 agent ID (ERC-721 token ID)
</ResponseField>

<ResponseField name="agents[].owner" type="string">
  Ethereum address of the agent's owner (checksummed)
</ResponseField>

<ResponseField name="agents[].metadata" type="object">
  Agent registration metadata from tokenURI (null if unavailable)
</ResponseField>

<ResponseField name="agents[].metadata.name" type="string">
  Agent name from registration metadata
</ResponseField>

<ResponseField name="agents[].metadata.description" type="string">
  Agent description from registration metadata
</ResponseField>

<ResponseField name="agents[].metadata.image" type="string">
  Agent image URI from registration metadata
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of agents in the Identity Registry
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of agents per page
</ResponseField>

<Tip>
  Agent IDs are 1-indexed ERC-721 token IDs. Burned or nonexistent tokens are automatically skipped, so a page may return fewer agents than the limit.
</Tip>

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.credprotocol.com/api/v2/agents?page=1&limit=10', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(`Showing ${data.agents.length} of ${data.total} agents`);
  data.agents.forEach(agent => {
    console.log(`Agent #${agent.agent_id} — owner: ${agent.owner}`);
  });
  ```

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

  response = requests.get(
      'https://api.credprotocol.com/api/v2/agents',
      params={'page': 1, 'limit': 10},
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  print(f"Showing {len(data['agents'])} of {data['total']} agents")
  for agent in data['agents']:
      print(f"Agent #{agent['agent_id']} — owner: {agent['owner']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "agents": [
      {
        "agent_id": 1,
        "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "metadata": {
          "name": "DeFi Score Agent",
          "description": "Credit scoring for DeFi protocols",
          "image": "ipfs://QmExample1"
        }
      },
      {
        "agent_id": 2,
        "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "metadata": {
          "name": "Sybil Detector",
          "description": "Sybil detection and identity verification",
          "image": "ipfs://QmExample2"
        }
      },
      {
        "agent_id": 3,
        "owner": "0x1234567890abcdef1234567890abcdef12345678",
        "metadata": null
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 10
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "limit must be between 1 and 100"
  }
  ```

  ```json 502 theme={null}
  {
    "detail": "Failed to read from Identity Registry contract"
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Agent Discovery">
    Browse all registered agents to find valid IDs for reputation feedback submission. Useful for building dashboards or agent directories.
  </Accordion>

  <Accordion title="Pagination">
    Use `page` and `limit` to iterate through the full registry. The `total` field tells you how many pages exist (`total_pages = ceil(total / limit)`).
  </Accordion>
</AccordionGroup>

## Performance

* **Response Time**: Typically 1-3 seconds depending on page size
* **Data Source**: On-chain `ownerOf()` calls to the Identity Registry on Base (chain 8453)
* **Maximum Page Size**: 100 agents per request