Skip to main content
Glama

Hosannaith

A pay-per-call x402 reliability oracle — live on Algorand Mainnet.

🔗 Live app: hosannaith.com · API: api.hosannaith.com · Repo: github.com/cameron4316/x402-oracle-server

The problem

As x402 turns APIs into pay-per-request services, agents increasingly pay endpoints they didn't build — with no way to know if an endpoint is actually reliable before sending real USDC. Dead or misbehaving endpoints silently waste money and break automated flows.

Related MCP server: fry-x402-mcp

What it does

Hosannaith is itself an x402 endpoint. It independently and continuously monitors other x402 endpoints and sells a verified reliability score on demand: uptime, correct 402 behaviour, and latency percentiles, backed by real accumulated history — with every response flagging its confidence ("history" for a stood-behind score, "one-shot" for a target queried for the first time). It's x402 monitoring x402.

GET https://api.hosannaith.com/reliability?target=<x402-endpoint-url>[&windowHours=24|168|720]

windowHours picks the history window: 24 hours (default), 168 (rolling 7 days) or 720 (rolling 30 days). The 7- and 30-day windows are the ones FINOS OpenEAGO Appendix D specifies for reliability_score, error_rate, latency_p99_ms (7 days) and availability_pct (30 days). The batch route takes the same value as "windowHours" in its JSON body.

Unpaid requests get 402 Payment Required with payment instructions; paid requests settle in USDC on Algorand via the GoPlausible facilitator and return JSON like:

Verifiable on-chain: first mainnet settlement — 3F2ATV3NCRVOI45IEL6OUKAWED3NQX246WJADESJB5CFR6LIXGCQ

{
  "target": "https://x402.example.com/api",
  "status": "pass",
  "score": 98.7,
  "detail": {
    "observations": 1439,
    "windowHours": 24,
    "uptimePct": 100,
    "correct402Pct": 100,
    "p50LatencyMs": 88,
    "p95LatencyMs": 127,
    "p99LatencyMs": 210,
    "confidence": "history",
    "availability_pct": 100,
    "error_rate_pct": 0,
    "protocol_conformance_pct": 100,
    "score_normalized": 0.987
  }
}

Reading the result

Field

Meaning

status

pass (score ≥ 90) · degraded (60–89) · fail (< 60) · unknown (not enough data)

score

0–100 composite: 0.6 × uptime + 0.4 × correct-402 − a latency penalty (up to 20). null below 5 observations.

uptimePct

Probes where the endpoint was serving: reachable and not a 5xx.

correct402Pct

Of the probes where the endpoint made a payment decision (a 402, or serving an unpaid 2xx), the share that correctly answered 402. Other 4xx (e.g. a 400 because our probe sends no input) are indeterminate and excluded. null if no probe was determinate.

p50/p95/p99LatencyMs

Latency percentiles of serving probes. p99LatencyMs is null below 20 samples (it would just be the slowest one); below 20 samples p95LatencyMs equals the slowest sample.

confidence

history (accumulated monitoring) · one-shot (first sighting, one live probe, score: null) · pending (batch only: no history yet, now enrolled).

mainnetPayablePct

Of the 402s that recorded their x402 payment requirements (paymentRequirementsSamples), the share whose requirements parse and name a known mainnet. A 402 alone proves gating, not that the endpoint can be paid on a mainnet (some answer with testnet-only requirements). Informational: not part of the score.

discoverablePct

Of those 402s, the share carrying the x402 bazaar discovery extension. Informational, never a score input.

acceptedNetworks

Payment networks those 402s named, as sent (CAIP-2 ids or x402 v1 names). The monitored endpoint chooses this text, so only well-formed network ids are repeated; anything else is left out.

currentSdkPayablePct

Like mainnetPayablePct, but counting only network ids the current x402 SDK accepts. Since @x402/core / @x402/avm 2.29.0 the SDK refuses Algorand's legacy full-genesis-hash id, so an endpoint offering only that id for Algorand is payable by older clients but not by up-to-date ones.

algorandIdForm

Which Algorand mainnet id the endpoint offers: spec (32-character CAIP-2 form), legacy (full genesis hash), both, or null. Offering both serves every client during the transition.

OpenEAGO SLO view

The same numbers in the SLO vocabulary used by agent registries and SLA/SLO feasibility checks. These are pure aliases (no new measurement) and are null exactly when their source is null.

SLO term

Field

Definition

availability

availability_pct

= uptimePct

error rate

error_rate_pct

= 100 − uptimePct: % of probes that were 5xx or unreachable (server-side errors). Client-side 4xx are indeterminate for an unpaid probe and are not counted.

protocol conformance

protocol_conformance_pct

= correct402Pct: % of gating-determinate probes that returned 402 rather than serving unpaid 2xx.

latency

p50LatencyMs, p95LatencyMs, p99LatencyMs

as above

registry score

score_normalized + confidence

score / 100, in [0, 1]

Machine-readable contract

  • /openapi.json: OpenAPI 3.1 description of every route, with each paid route's x402 terms in x-x402.

  • JSON Schemas (draft 2020-12): /schema/check-result.json, /schema/batch-result.json, /schema/problem.json.

  • Errors are RFC 9457 Problem Details (application/problem+json). The 402 Payment Required response is the x402 protocol's own.

  • Timestamps are RFC 3339 in UTC. Responses are additive-only: new optional fields may appear; existing fields never change name, type or meaning.

  • Signed results: when signing is enabled, every result (and every batch, as a whole) carries an ES256 signature over its RFC 8785 canonical JSON, verifiable against /.well-known/hosannaith-keys.json. Format, verification and key policy: docs/attestation.md.

Use it in your own code

A small TypeScript SDK wraps the full x402 pay-per-call handshake (402 → sign USDC payment → retry) so you don't have to implement it yourself:

import { getReliability } from 'hosannaith-client';

const result = await getReliability('https://some-x402-endpoint/api', {
  mnemonic: process.env.AVM_MNEMONIC!, // 25-word Algorand mnemonic, funded with USDC
});

console.log(result.score, result.detail.confidence);

See sdk/typescript/ for the client, a runnable example, and full usage docs.

Use it from any MCP agent (Model Context Protocol)

This repo also ships an MCP server in mcp/ — published to npm as hosannaith-mcp and listed in the official MCP Registry as io.github.cameron4316/hosannaith-mcp. It lets any Model Context Protocol client (Claude Desktop, Cursor, and other MCP agents) vet an x402 endpoint's reliability before paying it.

Built on the official MCP TypeScript SDK (@modelcontextprotocol/sdk), it exposes three MCP tools:

  • get_hosannaith_info — free; explains the score shape and how to act on it.

  • check_x402_reliability — paid; reliability score for one endpoint, settled as an x402 USDC micropayment on Algorand.

  • check_x402_reliability_batch — paid; score up to 50 endpoints in a single call.

Add it to an MCP client's config:

{
  "mcpServers": {
    "hosannaith": {
      "command": "npx",
      "args": ["-y", "hosannaith-mcp"],
      "env": { "AVM_MNEMONIC": "<25-word Algorand mnemonic, funded with USDC>" }
    }
  }
}

See mcp/ for the MCP server, its tools, and full setup docs.

There is also a hosted remote MCP server at https://api.hosannaith.com/mcp (Streamable HTTP, paid per call via x402 MCP). Its tools carry MCP annotations (paid tools: read-only, not destructive, not idempotent, open-world; the one side effect is that a target with no history gets one live probe and is enrolled for monitoring). Every call is recorded in an audit log with its on-chain settlement, or the quote offered when no payment was made; payment payloads and URL query strings are never logged.

Targets must be public http(s) URLs. Private, loopback, link-local and reserved addresses, internal host names and URLs with credentials are refused before any payment, on the HTTP API and both MCP servers. When probing, every redirect hop is checked, host names are resolved first, and the connection can only go to the addresses that were checked, so a public URL cannot redirect or resolve a probe into a private network, even if its DNS answer changes a moment later. A batch that contains a refused target is rejected as a whole and never charged.

Architecture and vision

The architecture is deliberately pluggable: every paid product implements the Check contract (see src/checks/types.ts). Reliability ships first; a compliance/attestation product for tokenization — the trust layer institutions need to bring real-world assets on-chain — is planned as a second Check + one route entry, with no rewrite of the payment plumbing.

The monitor (pnpm monitor, run continuously on the production droplet) records one observation per target per interval, append-only, to data/observations.jsonl. That history compounds and cannot be reconstructed later — every score above is backed by real, continuous observation, not a synthetic estimate.


For developers

Everything below is setup/reference for running Hosannaith locally (defaults to testnet) or understanding the codebase — not required to use the live API above.


1. Install

pnpm install
# runtime deps (exact packages from the official Algorand tutorial):
pnpm add @x402/core @x402/avm @x402/hono @x402-avm/extensions hono @hono/node-server dotenv

2. Configure

cp .env.example .env

Then edit .env:

  • AVM_ADDRESS — a testnet account funded with ALGO and opted in to testnet USDC.

  • Leave NETWORK=testnet and the GoPlausible FACILITATOR_URL as-is for now.

  • MONITOR_TARGETS already points at the Foundation's public example endpoint.

Testnet setup (accounts, faucets, USDC opt-in) follows the official tutorial: https://dev.algorand.co/resources/x402-on-algorand/

3. Run (two terminals)

pnpm monitor   # terminal 1 — starts collecting observations immediately
pnpm dev       # terminal 2 — starts the paid resource server on :4021

Sanity checks:

curl http://localhost:4021/health                 # -> {"ok":true,...}  (free)
curl -i "http://localhost:4021/reliability?target=https://x402.goplausible.xyz/examples/weather"
#  -> HTTP 402 Payment Required  (correct: it's a PAID route)

To pay and get the JSON back, point the tutorial's client at http://localhost:4021/reliability?target=... (client code: https://dev.algorand.co/resources/x402-on-algorand/#part-1-build-the-client).


File map

src/
  index.ts              Hono app + x402 wiring (edit sparingly)
  monitor.ts            Standalone monitor process (pnpm monitor)
  config.ts             Network/asset/facilitator config; testnet<->mainnet switch
  routes.config.ts      Paid routes + Bazaar discovery metadata  <-- add compliance route here
  checks/
    types.ts            The pluggable Check contract (shared by all products)
    registry.ts         Maps check id -> implementation
    reliability/
      monitor.ts        probe() + startMonitor()
      store.ts          Observation type + append-only JSONL store (swappable)
      score.ts          Turns observations into a 0-100 score
      index.ts          The reliability Check (reads store, computes score)
data/
  observations.jsonl    Append-only history (git-ignored; compounding)

Algorand network ids: both forms, during the transition

Algorand has two CAIP-2 ids in use for each network. The spec form (algorand: plus the first 32 characters of the genesis hash) is what @x402/avm exports as ALGORAND_MAINNET_CAIP2 / ALGORAND_TESTNET_CAIP2, and since @x402/core / @x402/avm 2.29.0 (x402-foundation/x402 #3894) it is the only form the x402 SDK accepts. The legacy full-genesis-hash form is what the GoPlausible facilitator originally required (reported in x402-foundation/x402 #3528). The facilitator now lists the spec form first and still accepts the legacy form until it is switched off with notice.

So every 402 from this server offers both, spec form first, otherwise identical (same price, payTo, asset and tag): clients on current SDKs pay the spec form, and older installs of our own clients keep paying the legacy form. src/config.ts imports the spec form from @x402/avm and checks at startup that it is exactly the legacy form truncated to 32 characters. The legacy option will be dropped, and this server's @x402 packages upgraded to 2.29+, in step with the facilitator's switch-off. Paid settlements on both ids are verified on mainnet.

To run this server against mainnet yourself: set NETWORK=mainnet and AVM_ADDRESS to a fixed payTo address opted in to mainnet USDC (ASA 31566704, already set in src/config.ts). The tag field in routes.config.ts's extra attributes activity to the Algorand Global x402 Challenge.

Notes

  • Tracks x402 protocol 2.26.0 (package.json pins ^2.26.0 for @x402/core, @x402/avm, and @x402/hono; the Algorand discovery/Bazaar package @x402-avm/extensions versions separately, currently ^2.6.1 — run pnpm ls for exact resolved versions).

  • Run pnpm typecheck after pnpm install to catch any API drift if you bump dependency versions.

Architecture as code

calm/hosannaith.architecture.json models Hosannaith in FINOS CALM (nodes, relationships and the paid-check, monitoring and verification flows), validated in CI with the official CALM CLI. See calm/README.md.

How Hosannaith relates to the FINOS AI Governance Framework is set out in docs/aigf-mapping.md: which mitigations apply, the evidence, what is not done, and what does not apply. The same mitigations are attached to the CALM model as controls.

Security

To report a vulnerability, email security@hosannaith.com or use GitHub's private vulnerability reporting. Please don't open a public issue. Scope and what to expect: SECURITY.md. Machine-readable: /.well-known/security.txt.

License

Licensed under the Apache License, Version 2.0. See NOTICE.

This repository was previously MIT-licensed. Code and npm releases published under MIT before the change (hosannaith-client 0.3.0 and earlier, hosannaith-mcp 0.2.1 and earlier) remain available under the MIT License.

Available Tools

3 tools
check_x402_reliabilityCheck an x402 endpoint reliability scoreA

Paid (small USDC payment via x402 on Algorand). Returns the Hosannaith reliability score for a target x402 endpoint URL so you can decide whether to trust it before routing payment to it. Requires the AVM_MNEMONIC environment variable on this server.

Inputs: targetUrl (required).

check_x402_reliability_batchBatch-check x402 endpoint reliabilityA

Paid (one small USDC payment via x402 on Algorand — $7 flat for up to 50 targets). Scores many x402 endpoints in a single call: pass a list of URLs, get a reliability score for each. Cheaper than checking each separately when you have a watchlist to vet before routing payments. Requires the AVM_MNEMONIC environment variable on this server.

Inputs: targetUrls (required).

get_hosannaith_infoAbout the Hosannaith reliability oracleA

Free. Explains what the Hosannaith x402 reliability oracle returns and how an agent should act on a score. Call this once before check_x402_reliability so you can interpret the result.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: one provides documentation, one checks a single endpoint, and one checks many endpoints in a batch. There is no overlap in purpose, so an agent can easily choose the right tool.

    Naming Consistency4/5

    All names use snake_case and follow a verb_noun style, with the batch tool predictably extending the single-check name. The only minor inconsistency is the differing verbs 'get' and 'check', but the meanings remain clear.

    Tool Count5/5

    Three tools perfectly match the narrow scope of a reliability oracle: an info tool, a single-check tool, and a batch-check tool. Each earns its place without redundancy or bloat.

    Completeness4/5

    The surface covers the core workflow—learn how to interpret scores, check one endpoint, and check many endpoints. A minor gap is the lack of per-score detail or historical lookup, but agents can still complete the primary task.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that lets your AI coding agent (Claude Code, OpenClaw, Codex, Cursor, etc.) discover and pay on-chain agents registered on ERC-8004, using Coinbase's official x402 protocol. No smart account. No bundler. No relay. Just your EOA, an HTTPS request, and an automatic 402 → sign → retry flow.
      3
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the x402 protocol that lets AI agents discover and call payment-gated HTTP APIs automatically.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for the agentfeed-algo x402 API, enabling paid per-call access to cross-venue liquidation data on Algorand. Provides tools to query liquidation volumes, cascade scores, symbol coverage, exchange integrity, and manage payments from your own Algorand account.
      51 npm
      MIT