Last updated 2026-06-10

Agents

All endpoints below are paywalled via x402. See x402 payment flow for how to sign a payment.

`GET /v1/agents`

Search and list agents.

curl -i "https://erc-8004.quicknode.com/v1/agents?network=base-mainnet&page=1&per_page=20"

Query params

Param	Type	Notes
`network`	string	Network slug, e.g. `base-mainnet`. Optional.
`owner`	string	Owner address (`0x…`). Optional.
`protocol`	string	Protocol tag: `a2a`, `mcp`, `http-api`, `custom`, or `unconfigured`. Optional.
`trait[]`	string	Trait tag; repeat the param to require multiple traits (AND semantics). See tags. Optional.
`include_testnets`	bool	Include agents on testnets. Default `false`.
`page`	int	1-indexed page number. Default `1`.
`per_page`	int	Page size, capped server-side.

# MCP agents that take x402 payments and are registered on more than one chain
curl -i "https://erc-8004.quicknode.com/v1/agents?protocol=mcp&trait[]=x402-paid&trait[]=multichain"

Response

{
  "data": [
    {
      "agent_id": 42,
      "network": { "slug": "base-mainnet", "name": "Base", "chain_id": 8453 },
      "owner_address": "0x…",
      "agent_uri": "ipfs://…",
      "protocol_tag": "mcp",
      "trait_tags": ["x402-paid", "multichain"],
      "feedback_count": 12,
      "validation_count": 3,
      "registered_at": "2026-04-01T12:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total_count": 137 }
}

Agent tags

Every agent carries one derived protocol_tag plus zero or more trait_tags. Both are recomputed automatically whenever the agent’s metadata is re-resolved, and activity-dependent traits refresh every ~10 minutes.

Protocol tag (exactly one):

Tag	Meaning
`a2a`	A service exposes A2A `skills`.
`mcp`	A service lists an MCP capability (`tools`, `resources`, `prompts`, `sampling`) or an `mcp://` / `…/mcp` endpoint.
`http-api`	Plain `http(s)://` endpoint with no A2A/MCP markers.
`custom`	Has services, but none match the above.
`unconfigured`	No services declared.

Trait tags (orthogonal, zero or more):

Tag	Meaning
`x402-paid`	Metadata declares `x402Support: true`.
`multichain`	Registration file lists more than one registration.
`tee-attested`	Metadata includes a `teeAttestation` entry.
`validated`	At least one completed validation.
`active`	Metadata declares `active: true` and the agent has feedback or validation activity in the last 30 days.

`GET /v1/agents/:agent_id`

Single agent detail. :agent_id is the on-chain ID. Pass network=<slug> to disambiguate when the same ID exists on multiple chains.

curl -i "https://erc-8004.quicknode.com/v1/agents/42?network=base-mainnet"

Response

{
  "data": {
    "agent_id": 42,
    "chain": "base-mainnet",
    "owner_address": "0x…",
    "agent_uri": "ipfs://…",
    "protocol_tag": "mcp",
    "trait_tags": ["x402-paid", "active"],
    "metadata": { "name": "...", "active": true },
    "registered_at": "2026-04-01T12:00:00Z",
    "feedback_count": 12,
    "validation_count": 3,
    "avg_validation_response": "P0DT4H12M",
    "reputation": { "score": 72, "confidence": "medium", "..." }
  }
}

reputation reflects a 30 s show-route cache; for fresher numbers call GET /v1/agents/:agent_id/reputation directly.

Errors

Code	When
404	Agent doesn’t exist on the requested network.

`GET /v1/agents/:agent_id/feedback`

Per-agent feedback feed.

curl -i "https://erc-8004.quicknode.com/v1/agents/42/feedback?network=base-mainnet&per_page=20"

Query params

Param	Type	Notes
`tag1`, `tag2`	string	Filter by tag.
`since`, `until`	ISO 8601	Time-bound.
`include_revoked`	bool	Default `false`.
`network`	string	Required when the same `:agent_id` exists on multiple chains.
`page`, `per_page`	int	Pagination.

`GET /v1/agents/:agent_id/validations`

Per-agent validations.

curl -i "https://erc-8004.quicknode.com/v1/agents/42/validations?network=base-mainnet"

Query params

Param	Type	Notes
`tag`	string	Filter by validation tag.
`has_response`	bool	Only validations with (or without) a response payload.
`since`, `until`	ISO 8601	Time-bound.
`network`	string	Required when ambiguous.
`page`, `per_page`	int	Pagination.

`GET /v1/agents/:agent_id/validations/summary`

Aggregate counts and tag breakdowns across an agent’s validations.

curl -i "https://erc-8004.quicknode.com/v1/agents/42/validations/summary?network=base-mainnet"

Query params

Param	Notes
`network`, `tag`, `validators`, `include_testnets`	All optional.

`GET /v1/agents/:agent_id/reputation`

Live reputation calculation. Bypasses the show-route cache; runs the formula against current data.

curl -i "https://erc-8004.quicknode.com/v1/agents/42/reputation?network=base-mainnet"

Response

{
  "data": {
    "score": 72,
    "confidence": "medium",
    "formula_version": "v1.3",
    "sub_scores": { "feedback": 80, "validation": 65, "sybil_resistance": 70, "reliability": 75 },
    "signals": { "..." }
  }
}

See the reputation formula for the full breakdown.