Agent Verification API

Confirms that an AI agent/service is who it claims to be. NEXUS candidate #3 -- manual build, not FORGE-generated, extending the domain-verification engine already live in production on live-entity-verification (Railway, free -- see below) with two new agent-specific signals.

• POST /verify-agent-identity {"domain": "...", "entity_name": "...", "agent_endpoint_url": "..." (optional)} -- charged $0.35 via x402 (Base Sepolia testnet).

• MCP tool verify_agent_identity at /mcp -- currently free, see "Known limitations".

• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (has x-payment-info).

What it actually checks

Fuses two independent lenses into one verdict:

1. Domain existence (the live-entity-verification engine, ported unchanged -- WHOIS + Certificate Transparency + Wayback Machine + DNS operational maturity, fused with the same calibrated Bayesian priors).

2. Agent liveness (new, only runs if agent_endpoint_url is given): a real GET of {agent_endpoint_url}/.well-known/agent-card.json, and a real MCP initialize handshake at {agent_endpoint_url}/mcp -- not just an HTTP 200 check. Also verifies the agent-card's own declared url is bound to domain (catches an agent card hosted somewhere unrelated to the entity it claims to represent).

Verdicts, most-trusted first: VERIFIED_LIVE_AGENT, VERIFIED_LIVE_DOMAIN_ONLY (no agent_endpoint_url given), DOMAIN_VERIFIED_AGENT_UNREACHABLE, AGENT_DOMAIN_MISMATCH, LIKELY_HALLUCINATED_AGENT, UNVERIFIED_AGENT. Full semantics in the endpoint's own docstring / OpenAPI description.

Why $0.35 (vs $0.01 for the sibling url-metadata-api)

Real cost per call is meaningfully higher: paid WHOIS lookup (~$0.002/call via Whoxy) plus 5-6 real outbound checks (WHOIS, CT, Wayback, DNS, agent-card fetch, MCP handshake) instead of one fetch. $0.35 is the midpoint of the $0.30-0.50 range for identity-verification-class services in the x402 ecosystem.

Relationship to live-entity-verification

live-entity-verification (Railway, live-entity-verification-production.up.railway.app, free, no x402, asset_registry.status='active' since 2026-08-20) is a separate, still-live asset -- this candidate reuses its domain-verification code (ported into main.py here, not imported cross-service) but does not replace or modify it. Don't touch that Railway service as part of work on this one without checking both.

Deploy target: Cloud Run, not Railway

Same pipeline as candidate #4 (url-metadata-api) -- see skills/infra-deploy-ops.

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
./scripts/deploy_cloud_run.sh agent-verification-api manual_assets/agent-verification-api

# 2. Grab the printed *.run.app URL, then (only if it differs from env-vars.deploy.yaml's guess):
gcloud run services update agent-verification-api --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

No numpy/scipy dependency (removed after the first deploy attempt failed Cloud Buildpacks' Python-3.14 scipy source build, which needs a Fortran compiler not present in the build image -- _fuse_signals_naive_bayes/ _compute_evidence_quality use plain math.log/math.exp/a small _clip helper instead; the one expit import from the original engine was actually unused dead code, dropped).

Known limitations (left unfixed on purpose -- CLAUDE.md SS3, no gate without evidence it's needed)

• MCP tool calls are not charged. Same in-process-call pattern (and same reason) as url-metadata-api: the MCP tool calls the shared verification function directly, not via HTTP re-entry into the ASGI app.

• No per-caller rate limiting. Fine for a 7-day disposable measurement; add if it survives.

• SSRF guard on agent_endpoint_url: IP-range based pre-connect check (rejects private/loopback/ link-local/reserved, including cloud metadata's 169.254.169.254). The agent-card fetch uses follow_redirects=False. The MCP handshake uses a custom httpx_client_factory that also disables redirects (the MCP client library's own default factory hardcodes follow_redirects=True with no opt-out via the public streamablehttp_client signature -- found in this candidate's pre-deploy security review: a malicious server could otherwise pass the pre-connect check, then 307-redirect the actual MCP request to an internal target). Neither guard defends against DNS rebinding between the check and the actual connect (accepted risk, same as candidate #4).

• name_matches_card is informational only, not verdict-gating -- self-reported agent names vary in formatting often enough that a hard mismatch gate would produce false negatives on real agents.

Pre-deploy quality gate (2026-08-22, from design not retroactive)

4 parallel review lenses ran against main.py before the first deploy. Real findings, all fixed before shipping:

• Security (critical): the MCP-handshake SSRF guard was bypassed by the mcp library's hardcoded follow_redirects=True default -- fixed via a custom httpx_client_factory.

• Functional (critical): the ported DNS-maturity engine silently dropped 2 of 6 scoring components (DKIM, cross-resolver propagation consistency) despite the module docstring claiming an unchanged port -- restored, and parallelized (was sequential, up to ~48s worst-case per call).

• Functional: _classify_agent_verdict's reachability check used OR between agent-card-present and MCP-handshake-reachable, letting a dead MCP server with a stale-but-present agent-card pass as VERIFIED_LIVE_AGENT -- the exact "vaporware" case this asset exists to catch. Fixed to require the handshake specifically for the top verdict.

• Code quality: dead function, unused signal_mask threading, a dropped explanatory comment -- all cleaned up.

• Buyer experience: the REST response was undocumented in OpenAPI (response_model added), the 6-value verdict enum had no semantic explanation anywhere reachable pre-payment (added to the endpoint docstring), and the fact that a 400/422 is still charged (ASGI middleware settles before FastAPI validation runs) was underdisclosed (added to agent-card.json's protocol_note and the endpoint docstring).

Measurement (candidate #3, 7-day window)

7-day window from first real deploy (2026-08-22 -> decision point 2026-08-29). Source of truth: traffic_events/revenue_events/mcp_call_events tables (asset_name = 'agent-verification-api'), not Cloud Run logs. First real call already confirmed same-session: real x402 payment settled on-chain, real revenue_events row (amount_eur=0.35, pricing_model=x402), verified against the live url-metadata-api Cloud Run service as the test agent (agent-card fetched, real MCP handshake succeeded, domain-binding confirmed). Day 7: if zero real traffic (filtering crawlers), pause/delete the Cloud Run service (gcloud run services delete agent-verification-api --region us-central1 --project nexus-505016).