DEVELOPER INFRASTRUCTURE • REST API

AgentProof API Reference

A free, public REST API for querying onchain agent reliability data on BNB Chain. No API key required. CORS enabled across all endpoints — seamlessly query from frontends, smart contracts, or autonomous orchestrators.

Production Base URL

https://agentproof-rho.vercel.app/api/v1

FREE · NO API KEYCORS ENABLED (*)

Authentication

None required

Rate Limiting

Fair use

Response Format

JSON

CORS

All origins (*)

Cache

30s CDN cache

Versioning

/api/v1/*

Endpoints

Method	Path	Description	Cache
GET	`/health`	Service health & probe freshness	No cache
GET	`/methodology`	Scoring methodology versions & docs	5 min
GET	`/agents`	Paginated list of monitored agents	30 s
GET	`/agents/:chain/:id`	Single agent identity & metadata	30 s
GET	`/agents/:chain/:id/reliability`	Uptime % & latency across 24h / 7d / 30d	30 s
GET	`/agents/:chain/:id/reputation-integrity`	Review diversity & integrity signals	60 s
GET	`/agents/:chain/:id/services`	Declared service endpoints & protocols	30 s
GET	`/agents/:chain/:id/observations`	Raw probe observation history	No cache
GET	`/agents/:chain/:id/badge.svg`	Embeddable live SVG badge	60 s

Endpoint Reference

GET/health

Returns service status and the timestamp of the most recent completed probe run. Use freshness to verify data is current (FRESH = run within last 3 hours).

curl "https://agentproof-rho.vercel.app/api/v1/health"

▸ Sample Response

{
  "status": "ok",
  "service": "agentproof",
  "timestamp": "2026-09-07T19:41:07.093Z",
  "version": "0.1.0",
  "monitoring": {
    "status": "active",
    "latestRunAt": "2026-09-07T19:40:13.358Z",
    "freshness": "FRESH"
  }
}

GET/agents

Paginated list of all monitored ERC-8004 agents. Supports cursor-based pagination via nextCursor. Accepts chain aliases like bsc, 56, bnb.

Query Parameters

chainFilter by chain: bsc (or 56, bnb)

limitItems per page. Default: 20, max: 100

cursorPagination cursor from previous nextCursor

curl "https://agentproof-rho.vercel.app/api/v1/agents?chain=bsc&limit=3"

▸ Sample Response

{
  "data": {
    "items": [
      {
        "id": "bsc:49637",
        "chain": "bsc",
        "onchainId": "49637",
        "registryAddress": "0x8004a169fb4a3325136eb29fa0ceb6d2e539a432",
        "provenance": {
          "source": "INDEXER",
          "origin": "8004scan",
          "observedAt": "2026-09-07T13:40:13.358Z"
        }
      }
    ],
    "nextCursor": "bsc:338366"
  },
  "generatedAt": "2026-09-07T20:26:37.417Z"
}

GET/agents/:chain/:id/reliability

The flagship endpoint. Returns empirical availability %, latency percentiles, and consecutive failure counts across three sliding windows: 24h, 7d, and 30d. All measurements are independent — AgentProof probes each agent, not the agent reporting its own status.

curl "https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/reliability"

▸ Sample Response (Live bsc:2518 - PancakeSwap)

{
  "data": {
    "windows": {
      "24h": {
        "agentId": "bsc:2518",
        "window": "24h",
        "sufficientData": true,
        "dataSufficiency": "MODERATE",
        "observationCount": 32,
        "successCount": 28,
        "failureCount": 4,
        "availabilityPct": 87.5,
        "medianLatencyMs": 270,
        "p95LatencyMs": 5732,
        "lastSuccessfulProbeAt": "2026-09-07T13:41:05.287Z",
        "lastProbeAt": "2026-09-07T13:41:05.287Z",
        "consecutiveFailures": 0,
        "methodologyVersion": "0.1.0",
        "computedAt": "2026-09-07T20:26:00.424Z"
      },
      "7d": {
        "agentId": "bsc:2518",
        "window": "7d",
        "sufficientData": true,
        "dataSufficiency": "STRONG",
        "observationCount": 240,
        "successCount": 196,
        "failureCount": 44,
        "availabilityPct": 81.67,
        "medianLatencyMs": 269,
        "p95LatencyMs": 721
      },
      "30d": {
        "agentId": "bsc:2518",
        "window": "30d",
        "sufficientData": true,
        "dataSufficiency": "MODERATE",
        "observationCount": 312,
        "successCount": 259,
        "failureCount": 53,
        "availabilityPct": 83.01,
        "medianLatencyMs": 267,
        "p95LatencyMs": 583
      }
    }
  },
  "generatedAt": "2026-09-07T20:26:00.439Z"
}

Key Response Fields

Field	Type	Description
`availabilityPct`	number \| null	Empirical uptime % over the window. Null if no probes yet.
`dataSufficiency`	string	INSUFFICIENT / LIMITED / MODERATE / STRONG — weight decisions accordingly.
`medianLatencyMs`	number \| null	Median response latency in ms across successful probes.
`p95LatencyMs`	number \| null	95th percentile latency. High = occasional latency spikes.
`consecutiveFailures`	number	Current sequential failure count. >3 means agent is likely degraded.
`lastProbeAt`	ISO 8601	Timestamp of the most recent probe attempt.
`methodologyVersion`	string	Scoring formula version so historical data stays interpretable.

GET/agents/:chain/:id

Resolves a single agent's onchain identity and metadata. :id accepts both bsc:2518 and plain 2518. Returns 404 if AgentProof has not yet indexed the agent.

curl "https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518"

GET/agents/:chain/:id/services

Returns the agent's declared service endpoints as published in their onchain ERC-8004 metadata. Protocol can be HTTP, A2A, MCP, or UNKNOWN.

curl "https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/services"

GET/agents/:chain/:id/reputation-integrity

Computes reviewer diversity metrics to flag potential review manipulation or Sybil behavior. Returns reviewerConcentration and integritySignals for detected anomalies.

curl "https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/reputation-integrity"

GET/agents/:chain/:id/observations

Raw append-only probe log. Every probe AgentProof has ever run against this agent, timestamped with outcome, latency, HTTP status, and failure reason. Supports since, until, and serviceId filters.

curl "https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/observations?limit=10"

GET/agents/:chain/:id/badge.svg

Dynamic SVG badge for embedding in GitHub READMEs, documentation, or websites. Automatically reflects the agent's live 24h uptime % and median latency. Color-coded: green ≥ 90%, amber ≥ 70%, red below.

↑ Live badge — bsc:2518 (PancakeSwap)

<!-- Markdown -->
[![AgentProof](https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/badge.svg)](https://agentproof-rho.vercel.app/agents/bsc/bsc:2518)

<!-- HTML -->
<img src="https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/badge.svg" alt="AgentProof" />

Integration Examples

Drop-in guard functions for checking agent health before delegating tasks or initiating onchain payments.

TypeScript / Node.js

async function isAgentHealthy(agentId: string): Promise<boolean> {
  const res = await fetch(`https://agentproof-rho.vercel.app/api/v1/agents/bsc/${agentId}/reliability`);
  if (!res.ok) return false;
  const { data } = await res.json();
  const w24 = data?.windows?.['24h'];
  // Require ≥90% uptime and no consecutive failures
  return (w24?.availabilityPct ?? 0) >= 90.0 && (w24?.consecutiveFailures ?? 0) === 0;
}

Python

import requests

def is_agent_healthy(agent_id: str) -> bool:
    resp = requests.get(
        f"https://agentproof-rho.vercel.app/api/v1/agents/bsc/{agent_id}/reliability",
        timeout=3
    )
    if resp.status_code != 200:
        return False
    w24 = resp.json().get("data", {}).get("windows", {}).get("24h", {})
    return w24.get("availabilityPct", 0) >= 90.0 and w24.get("consecutiveFailures", 0) == 0

curl (shell)

# Get 24h uptime % for agent bsc:2518
curl -s "https://agentproof-rho.vercel.app/api/v1/agents/bsc/bsc:2518/reliability" \
  | jq '.data.windows["24h"].availabilityPct'

# Output: 87.5

Error Codes

HTTP	code	Description
200	`—`	Success. Data is in the data envelope.
400	`VALIDATION_ERROR`	Invalid query parameters (e.g. unknown chain).
404	`NOT_FOUND`	Agent not yet indexed by AgentProof.
405	`METHOD_NOT_ALLOWED`	Only GET is supported on this route.
500	`INTERNAL_ERROR`	Database or upstream error. Retry after a moment.

Open Infrastructure

AgentProof is open-source and free to use. The API has no rate limits beyond fair-use abuse prevention. All measurements are produced independently by AgentProof — agents do not self-report. Source code: github.com/ademikelz19-hub/agentproof