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
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
AVM_MNEMONIC=<secret> claude mcp add io.github.cameron4316-hosannaith-mcp -- npx -y hosannaith-mcp@0.3.2在終端機中執行。
{ "mcpServers": { "io.github.cameron4316-hosannaith-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "AVM_MNEMONIC": "<secret>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
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
Check x402 endpoint reliability on Algorand before an agent routes a payment there.
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.
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>
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,
"confidence": "history"
}
}
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.
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.
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.
Everything below is setup/reference for running Hosannaith locally (defaults to testnet) or understanding the codebase — not required to use the live API above.
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
cp .env.example .env
Then edit .env:
AVM_ADDRESS — a testnet account funded with ALGO and opted in to testnet USDC.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/
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).
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)
src/config.ts's FACILITATOR_TESTNET_CAIP2 and MAINNET_CAIP2 are hardcoded, not imported
from @x402/avm — and that's deliberate, not an oversight. Here's the real story:
@x402/avm's ALGORAND_TESTNET_CAIP2 / ALGORAND_MAINNET_CAIP2 exports are the spec-correct,
truncated CAIP-2 form (per the Algorand CAIP-2 namespace profile; fixed upstream in
x402-foundation/x402 issue #2904 / PR #2931). The package is not the problem. The live
GoPlausible facilitator (facilitator.goplausible.xyz) runs GoPlausible/x402-avm, a fork
hundreds of commits behind upstream that predates that fix — so its /supported endpoint still
advertises the legacy, non-compliant full-genesis-hash form, on both testnet and mainnet. This
server hardcodes the values the facilitator actually expects, verified live via
curl https://facilitator.goplausible.xyz/supported, not guessed and not the package constant.
If GoPlausible syncs their fork to the upstream fix, both constants must be reverted back to
importing from @x402/avm — see the comments at each constant in src/config.ts for the full
reasoning. A tracking report was filed upstream against x402-foundation/x402 (GoPlausible's own
fork has issue creation restricted, so that wasn't an option).
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.
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).pnpm typecheck after pnpm install to catch any API drift if you bump dependency versions.Check x402 endpoint reliability on Algorand before an agent routes a payment there.
{ "mcpServers": { "io.github.cameron4316-hosannaith-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "AVM_MNEMONIC": "<secret>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數:AVM_MNEMONIC。
Hosannaith 透過 stdio 在本機執行。
上次檢查時間:2026-11-18。 Check x402 endpoint reliability on Algorand before an agent routes a payment there.