REST API Reference

The Agent Registry REST API is a read-only HTTP wrapper around the on-chain registry contract. It provides a public query layer for browsing agent records and performing KYA (Know Your Agent) compliance checks.

Source: api/server.js Default port: 3000

---

Configuration

Environment Variable	Default	Description
PORT	3000	HTTP server port
RPC_URL	https://sepolia.base.org	Blockchain RPC endpoint
REGISTRY_ADDRESS	-- (required)	Deployed Agent Registry contract address

REGISTRY_ADDRESS=0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23 node api/server.js

---

Rate Limiting

All endpoints are rate-limited to 60 requests per minute per IP.

Header	Description
X-RateLimit-Remaining	Requests remaining in the current window

When the limit is exceeded, the API returns:

{
  "error": "Rate limit exceeded. Try again in 1 minute."
}

HTTP status: 429 Too Many Requests

---

Caching

Responses are cached in memory to reduce RPC calls to the blockchain.

Cache Scope	TTL	Endpoints
Agent data	5 minutes	/stats, /stats/detailed, /agent/:id, /agents, /agents/compliance, /revenue/aggregate
Lineage	10 minutes	/agent/:id/lineage
KYA checks	1 minute	/kya/:wallet
Revenue history	No cache	/agent/:id/revenue

Cache bypass

The cache is refreshed automatically after the TTL expires. There is currently no manual cache invalidation endpoint.

---

Endpoints Overview

Method	Endpoint	Description	Cache TTL
GET	/health	Health check	--
GET	/api/v1/stats	Registry statistics	5 min
GET	/api/v1/stats/detailed	Detailed stats with distributions	5 min
GET	/api/v1/agent/:id	Full agent record	5 min
GET	/api/v1/agents	Paginated agent list	5 min
GET	/api/v1/agents/compliance	All agents with compliance status	5 min
GET	/api/v1/agent/:id/lineage	Recursive lineage tree	10 min
GET	/api/v1/agent/:id/revenue	Revenue history (paginated)	--
GET	/api/v1/revenue/aggregate	Revenue totals by currency/category	5 min
GET	/api/v1/kya/:wallet	KYA compliance check	1 min

---

Health Check

GET /health

Returns the server's operational status and configuration.

curl https://api.theagentregistry.org/health

Response:

{
  "status": "ok",
  "registry": "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  "rpc": "https://sepolia.base.org"
}

---

Registry Statistics

GET /api/v1/stats

Basic registry-wide statistics.

curl https://api.theagentregistry.org/api/v1/stats

Response:

{
  "totalAgents": 13,
  "registryAddress": "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  "chain": "https://sepolia.base.org"
}

---

GET /api/v1/stats/detailed

Detailed statistics including status distribution, generation distribution, compliance rates, revenue totals, and recent registrations.

curl https://api.theagentregistry.org/api/v1/stats/detailed

Response:

{
  "totalAgents": 13,
  "registryAddress": "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  "chain": "https://sepolia.base.org",
  "statusDistribution": {
    "Active": 10,
    "Suspended": 1,
    "Revoked": 0,
    "Terminated": 2
  },
  "generationDistribution": {
    "0": 8,
    "1": 4,
    "2": 1
  },
  "complianceRate": "76.9",
  "compliantCount": 10,
  "totalRevenue": {
    "USDC": 150000,
    "EUR": 25000
  },
  "recentRegistrations": [
    {
      "agentId": 13,
      "creator": "0x...",
      "haftungsperson": "0x...",
      "agentWallet": "0x...",
      "registeredAt": "2025-01-20T10:30:00.000Z",
      "status": "Active"
    }
  ]
}

Field	Type	Description
statusDistribution	object	Count of agents per status
generationDistribution	object	Count of agents per generation depth
complianceRate	string	Percentage of agents that are active and compliant
compliantCount	number	Number of compliant agents
totalRevenue	object	Revenue totals keyed by currency
recentRegistrations	array	Last 10 registered agents (newest first)

---

Agent Records

GET /api/v1/agent/:id

Full agent record with compliance status and children -- the "Handelsregisterauszug".

Path Parameters:

Parameter	Type	Description
id	number	Agent ID

curl https://api.theagentregistry.org/api/v1/agent/1

Response:

{
  "agent": {
    "agentId": 1,
    "creator": "0x9dAC97B7b4F123F943efCF1Cb77aBDfe44c3421C",
    "haftungsperson": "0x9dAC97B7b4F123F943efCF1Cb77aBDfe44c3421C",
    "agentWallet": "0xAgentWalletAddress",
    "constitutionHash": "0xabc123...",
    "capabilityHash": "0xdef456...",
    "operationalScope": "Automated web research",
    "parentAgentId": 0,
    "generation": 0,
    "selfModifying": false,
    "registeredAt": "2025-01-15T12:00:00.000Z",
    "lastAttestation": "2025-01-22T12:00:00.000Z",
    "lastRevenueReport": "2025-01-20T08:00:00.000Z",
    "status": "Active"
  },
  "children": [2, 3],
  "compliance": {
    "isActive": true,
    "attestationCurrent": true,
    "secondsSinceAttestation": 86400,
    "childCount": 2,
    "status": "Active"
  }
}

Error (agent not found):

{
  "error": "Agent not found: ..."
}

HTTP status: 404

---

GET /api/v1/agents

Paginated list of all agents with optional status filtering.

Query Parameters:

Parameter	Type	Default	Description
page	number	1	Page number (1-indexed)
limit	number	20	Results per page (max: 100)
status	string	--	Filter by status: Active, Suspended, Revoked, Terminated

curl "https://api.theagentregistry.org/api/v1/agents?page=1&limit=10&status=Active"

Response:

{
  "total": 10,
  "page": 1,
  "limit": 10,
  "totalPages": 1,
  "data": [
    {
      "agentId": 1,
      "creator": "0x...",
      "status": "Active",
      "registeredAt": "2025-01-15T12:00:00.000Z"
    }
  ]
}

---

GET /api/v1/agents/compliance

All agents with compliance status, sorted by attestation age (most stale first). Useful for monitoring which agents are about to lose compliance.

curl https://api.theagentregistry.org/api/v1/agents/compliance

Response:

{
  "total": 13,
  "data": [
    {
      "agentId": 5,
      "creator": "0x...",
      "status": "Active",
      "compliance": {
        "isActive": true,
        "attestationCurrent": false,
        "secondsSinceAttestation": 700000,
        "childCount": 0,
        "status": "Active"
      }
    }
  ]
}

---

Lineage

GET /api/v1/agent/:id/lineage

Recursive lineage tree from a root agent down through all descendants.

Path Parameters:

Parameter	Type	Description
id	number	Root agent ID

Limits

• Maximum tree depth: 15 levels
• Maximum children per node: 50 (with a note if truncated)

curl https://api.theagentregistry.org/api/v1/agent/1/lineage

Response:

{
  "agentId": 1,
  "wallet": "0x...",
  "generation": 0,
  "status": "Active",
  "children": [
    {
      "agentId": 2,
      "wallet": "0x...",
      "generation": 1,
      "status": "Active",
      "children": [
        {
          "agentId": 4,
          "wallet": "0x...",
          "generation": 2,
          "status": "Active",
          "children": []
        }
      ]
    },
    {
      "agentId": 3,
      "wallet": "0x...",
      "generation": 1,
      "status": "Terminated",
      "children": []
    }
  ]
}

---

Revenue

GET /api/v1/agent/:id/revenue

Paginated revenue history for a specific agent.

Path Parameters:

Parameter	Type	Description
id	number	Agent ID

Query Parameters:

Parameter	Type	Default	Description
limit	number	100	Results per page (max: 500)
offset	number	0	Offset from the beginning

curl "https://api.theagentregistry.org/api/v1/agent/1/revenue?limit=10&offset=0"

Response:

{
  "total": 3,
  "offset": 0,
  "limit": 10,
  "data": [
    {
      "amount": 15000,
      "currency": "USDC",
      "category": "data_collection",
      "periodStart": "2025-01-08T00:00:00.000Z",
      "periodEnd": "2025-01-15T00:00:00.000Z",
      "reportedAt": "2025-01-15T12:00:00.000Z"
    }
  ]
}

---

GET /api/v1/revenue/aggregate

Registry-wide revenue totals broken down by currency and category.

curl https://api.theagentregistry.org/api/v1/revenue/aggregate

Response:

{
  "totalReports": 25,
  "totalAmount": 500000,
  "byCurrency": {
    "USDC": 450000,
    "EUR": 50000
  },
  "byCategory": {
    "data_collection": 300000,
    "research": 150000,
    "general": 50000
  }
}

---

KYA (Know Your Agent)

GET /api/v1/kya/:wallet

The core compliance endpoint for infrastructure providers. Returns whether a wallet belongs to a registered, compliant agent, along with the full agent record if found.

Path Parameters:

Parameter	Type	Description
wallet	string	Ethereum wallet address (checksummed or lowercase)

curl https://api.theagentregistry.org/api/v1/kya/0xAgentWalletAddress

Response (compliant agent):

{
  "wallet": "0xAgentWalletAddress",
  "isRegistered": true,
  "isCompliant": true,
  "agent": {
    "agentId": 1,
    "creator": "0x...",
    "haftungsperson": "0x...",
    "agentWallet": "0xAgentWalletAddress",
    "operationalScope": "Automated web research",
    "status": "Active",
    "registeredAt": "2025-01-15T12:00:00.000Z",
    "lastAttestation": "2025-01-22T12:00:00.000Z"
  },
  "checkedAt": "2025-01-23T10:00:00.000Z"
}

Response (unregistered wallet):

{
  "wallet": "0xUnknownWallet",
  "isRegistered": false,
  "isCompliant": false,
  "agent": null,
  "checkedAt": "2025-01-23T10:00:00.000Z"
}

Integration Pattern

Infrastructure providers should check the isCompliant field. An agent can be registered but non-compliant if its attestation has expired (>7 days since last attestation) or if it has been suspended/revoked.

const res = await fetch(`https://api.theagentregistry.org/api/v1/kya/${wallet}`);
const data = await res.json();

if (data.isCompliant) {
  // Provision services
} else if (data.isRegistered) {
  // Registered but non-compliant -- request attestation renewal
} else {
  // Not registered -- deny access or request registration
}

---

Error Responses

All error responses follow a consistent format:

{
  "error": "Description of what went wrong"
}

HTTP Status	Meaning
400	Bad request (missing or invalid parameters)
404	Agent or resource not found
429	Rate limit exceeded
500	Internal server error (RPC failure, contract revert)