API Reference

Every endpoint the hosted verification service exposes.

Base URL

Use your own deployed instance’s URL (see Deployment), or the operator’s hosted instance if you’re a customer rather than a self-hoster.

Authentication

None beyond x402 payment itself — POST /verify-facilitator is gated by the x402 payment protocol, not an API key. GET / and GET /health are unauthenticated.

---

GET /

Service metadata — a human-readable description of what this instance does and how to call it.

200

{
  "name": "Ward — facilitator verification service",
  "description": "Pay once, get a real adversarial-test report on whether an x402 facilitator honors its correctness invariants.",
  "endpoints": {
    "verify": "POST /verify-facilitator { facilitatorUrl: string } — $1.00",
    "health": "GET /health"
  }
}

---

GET /health

Liveness check — used as this service’s own health check path when deployed (see Deployment).

200

{ "status": "ok" }

---

POST /verify-facilitator

Runs Ward’s full guarantee suite — all eight correctness properties (U1–U5, A1–A3) — against a facilitator URL you provide, and returns a pass/fail report with reproducible evidence.

facilitatorUrl · string · required

The base URL of the x402 facilitator to test — e.g. https://your-facilitator.example.com. Must implement the standard /verify, /settle, and /supported endpoints.

Pricing

Price

$1.00 per call

Scheme

exact

Network

Algorand TestNet

Payment is enforced by @x402/express’s paymentMiddleware() — a request without a valid PAYMENT-SIGNATURE header receives a standard x402 402 Payment Required response describing the exact payment requirements; retry the same request with a valid signed payment attached, exactly as any x402-compliant client would.

The route is tagged extra: { tag: "x402-global-challenge" } for Bazaar/leaderboard attribution, and is registered with declareDiscoveryExtension so it’s discoverable through the payment facilitator’s /discovery/resources catalog once a real payment has settled through it.

Success response

200

{
  "ok": true,
  "report": {
    "runId": "b3f2b6b0-...-...",
    "timestamp": "2026-08-17T09:12:03.441Z",
    "facilitator": { "name": "https://your-facilitator.example.com", "commit": "unknown", "chain": "algorand-testnet" },
    "summary": { "total": 8, "passed": 8, "failed": 0, "skipped": 0 },
    "mustHaveIds": ["U1", "U2", "U3", "U4", "A1"],
    "results": [
      {
        "id": "A1",
        "name": "atomic group integrity",
        "category": "algorand",
        "passed": true,
        "mustHave": true,
        "evidenceSummary": "fee-payer leg amount > 0 ...: OK; ...",
        "durationMs": 2143,
        "source": "Algorand atomic transaction groups + @x402/avm's verifyFeePayerTransaction; all four USENIX violation classes",
        "detail": { "rows": [ { "label": "...", "ok": true, "detail": "...", "tag": "Asset Theft" } ] }
      }
    ]
  }
}

The report body is a ReportSummary (see src/core/report-summary.ts) — a compact, customer-facing reduction of the full WardReport the CLI writes to reports/latest.json. It strips raw wire payloads and msgpack blobs down to human-readable rows/facts per invariant while keeping every pass/fail result, its source citation, and its mustHave status.

Error responses

400

{ "ok": false, "error": "facilitatorUrl (string) is required in the request body" }

Status	Meaning
400	facilitatorUrl was missing or not a string.
402	Standard x402 payment-required response — no valid payment attached yet.
502	Payment succeeded, but the check itself couldn’t complete — e.g. the submitted facilitatorUrl was unreachable or returned malformed responses.

Deploy your own instance