# Hosannaith — x402 reliability oracle

Reliability scoring for x402 endpoints on Algorand. Hosannaith independently and continuously
monitors other x402 endpoints and sells a verified reliability score — uptime, correct-402
behaviour, and latency percentiles — so an agent can decide whether an endpoint is safe to pay
before routing USDC to it. Hosannaith is itself an x402 endpoint.

Website: https://hosannaith.com
API base: https://api.hosannaith.com
Discovery: https://api.hosannaith.com/.well-known/x402

## Network
- Protocol: x402 v2
- Chain: Algorand mainnet
- Facilitator: https://facilitator.goplausible.xyz
- Network (CAIP-2): algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=
- Asset: USDC, ASA 31566704 (6 decimals)
- payTo: BEACJLUDOSVMS6SUQEUAHWRI4VAAX7G4CVFOL3DWH2R4XHTLXT6VG5TFYU
- Challenge tag: x402-global-challenge (present on every paid 402)

## How to pay (x402 flow)
1. GET the paid endpoint with no payment -> HTTP 402 Payment Required, with a PAYMENT-REQUIRED
   header describing the requirement.
2. Pay the advertised requirement with any x402 client (exact scheme on the Algorand AVM).
3. Retry the same request with the PAYMENT-SIGNATURE header.
4. On success -> HTTP 200 with the JSON result below, settled in USDC on Algorand mainnet.

## Paid endpoints
GET /reliability?target=<x402-endpoint-url>   -   $1.00 (1000000 uUSDC)
Score the reliability of a target x402 endpoint.

Request
- target (query, required): full URL of the x402 endpoint to score.

Response (application/json)
{
  "target": "<url>",
  "checkId": "reliability",
  "status": "pass" | "degraded" | "fail" | "unknown",
  "score": <number 0-100 | null>,
  "detail": {
    "observations": <int>,
    "windowHours": 24,
    "uptimePct": <number 0-100 | null>,
    "correct402Pct": <number 0-100 | null>,
    "p50LatencyMs": <int | null>,
    "p95LatencyMs": <int | null>,
    "p99LatencyMs": <int | null>,
    "confidence": "history" | "one-shot",
    "availability_pct": <number 0-100 | null>,
    "error_rate_pct": <number 0-100 | null>,
    "protocol_conformance_pct": <number 0-100 | null>,
    "score_normalized": <number 0-1 | null>
  },
  "observedAt": "<RFC 3339 UTC timestamp>"
}

Field notes
- uptimePct: probes where the endpoint was serving (reachable and not 5xx).
- correct402Pct: of probes where the endpoint made a payment decision (402, or an unpaid 2xx),
  the share that answered 402. Other 4xx are indeterminate for an unpaid probe and excluded.
- p99LatencyMs is null below 20 latency samples; below 20 samples p95LatencyMs is the slowest one.
- OpenEAGO SLO aliases (same numbers, null when their source is null):
  availability_pct = uptimePct; error_rate_pct = 100 - uptimePct (5xx or unreachable);
  protocol_conformance_pct = correct402Pct; score_normalized = score / 100.
- Responses are additive-only: new optional fields may appear; existing ones never change.

How to use the result
- status: pass = score >= 90, degraded = 60-89, fail = < 60, unknown = not enough data yet.
- confidence: "history" = backed by accumulated monitoring; "one-shot" = first sighting, a single
  live probe (score may be null). A target queried for the first time is enrolled for ongoing
  monitoring, so confidence improves on subsequent calls.
- Decision rule for agents: before routing USDC to an unfamiliar x402 endpoint, call this first.
  If status is "fail" or the score is low, treat the endpoint as risky.

POST /reliability/batch   -   $7.00 (7000000 uUSDC), up to 50 targets
Score up to 50 x402 endpoints in one call. Flat price (x402 declares the price before the body is
seen, so it can't scale with count).

Request (application/json)
{ "targets": ["<x402-endpoint-url>", ...] }   // max 50

Response (application/json)
{
  "count": <int>,
  "requested": <int>,
  "capped": <bool>,
  "observedAt": "<RFC 3339 UTC timestamp>",
  "results": [ <same per-target shape as GET /reliability above> ]
}
Monitored targets return a history-based score; unmonitored targets return "unknown" and are
enrolled for ongoing monitoring.

## Free endpoints
GET /health                     - liveness check: {"ok":true,...}
GET /                           - service info (send Accept: application/json for JSON)
GET /.well-known/x402           - machine-readable discovery document
GET /.well-known/hosannaith-keys.json - public keys for verifying signed results
GET /reports/<id>.json          - signed, dated public reliability reports (free)
GET /openapi.json               - OpenAPI 3.1 description (paid terms in each operation's x-x402)
GET /schema/check-result.json   - JSON Schema of a reliability result
GET /schema/batch-result.json   - JSON Schema of a batch result
GET /schema/problem.json        - JSON Schema of an error body
GET /llms.txt                   - this file

## Signed results
When signing is enabled, every result (and every batch, as a whole) also carries:
  "spec_version": "1.0.0", "generated_at": "<RFC 3339 UTC>",
  "signature": { "alg": "ES256", "kid": "<RFC 7638 thumbprint>", "sig": "<base64url r||s>" }
The signature covers the RFC 8785 canonical JSON of the object without its own "signature".
In a batch, each result is signed on its own (so it can be forwarded and still verify) and the
batch signature also covers every per-result signature. Verify against the key with that kid in
/.well-known/hosannaith-keys.json; reject keys listed in revoked_keys.

## Errors
Errors from this server are RFC 9457 Problem Details (application/problem+json):
{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "...", "error": "..." }
The 402 Payment Required response is the x402 protocol's own (see "How to pay").