Integrates with Algorand for x402 pay-per-call micropayments, enabling paid reliability checks and batch checks to be settled in USDC on Algorand mainnet or testnet via the GoPlausible facilitator.
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
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
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 dotenvcp .env.example .envThen 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/
pnpm monitor # terminal 1 — starts collecting observations immediately
pnpm dev # terminal 2 — starts the paid resource server on :4021Sanity 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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| targetUrl | Yes | The full https URL of the x402 endpoint to evaluate, e.g. https://api.example.com/resource |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden, and it does well: it discloses that the call is paid (small USDC via x402 on Algorand) and requires the AVM_MNEMONIC environment variable. It omits the exact cost, failure behavior, and whether the payment is consumed on error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: cost/mechanism, purpose, and environmental prerequisite. The critical constraint (paid call) is front-loaded so an agent sees it before committing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no annotations and no output schema, the description covers cost, requirement, and purpose adequately. It could be more complete by hinting at the score's shape or failure modes, but nothing essential to invoking it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including a format hint and example URL, so the schema already documents the single parameter fully. The description adds no syntax beyond what the schema provides, which is the expected baseline here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Returns the ... reliability score') and resource ('target x402 endpoint URL') and the decision it supports. It does not explicitly distinguish itself from the sibling check_x402_reliability_batch, but the singular targetUrl and phrasing imply a single-endpoint check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: 'so you can decide whether to trust it before routing payment to it.' It does not name the batch sibling as an alternative for multiple-URL scenarios, so routing guidance between siblings is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| targetUrls | Yes | Up to 50 x402 endpoint URLs to score in one paid call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the call is paid ($7 flat for up to 50 targets, one small USDC payment via x402 on Algorand) and that it requires the AVM_MNEMONIC environment variable. It does not describe failure modes, timeouts, or what a returned score means, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences that open with cost, then behavior, then prerequisite. Slight redundancy ('up to 50 targets' and 'list of URLs' each appear twice), which costs it the top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-paid-param scoring tool with no annotations and no output schema, it covers cost, auth prerequisite, and batching limits. The one meaningful gap is that it never says what the reliability score itself represents or how to interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is a single parameter, so the schema already documents targetUrls, its URI format, and its 1-50 bounds. The description adds only the pricing-per-batch framing, which is not parameter syntax, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Scores many x402 endpoints in a single call') and makes the batch scope explicit ('pass a list of URLs, get a reliability score for each'), which cleanly differentiates it from the singular sibling check_x402_reliability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete usage context ('when you have a watchlist to vet before routing payments') and an economic rationale for batching ('Cheaper than checking each separately'). It does not explicitly name check_x402_reliability as the single-target alternative, so routing guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers useful context: the call is free (a cost disclosure) and it is purely informational ('Explains'), strongly implying no side effects. It stops short of explicitly stating there are no mutations or describing the shape of what is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the cost qualifier ('Free.'), then purpose, then the usage rule. Every clause earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param, read-only documentation tool with no output schema, the description covers what it explains, when to call it, and that it is free. It could say slightly more about what the returned guidance looks like, but it is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. There is nothing schema-wise to document, and the description correctly focuses on the tool's role rather than fabricating parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Explains) and resource (what the Hosannaith x402 reliability oracle returns and how to act on a score), and it is clearly differentiated from the sibling check_x402_reliability tools, which perform the actual checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit ordering rule — 'Call this once before check_x402_reliability so you can interpret the result' — naming the exact sibling and the condition that selects this tool. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1check_x402_reliabilitycheck_x402_reliability_batchget_hosannaith_infoScored across 3 tools
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.
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.
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.
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.
Programmatic web-scraping MCP server powered by x402 micro-transactions on Base.
Experimental MCP server for current empirical verification of explicit public HTTPS endpoint claims.
Broker + MCP server for last-bidder-wins on-chain games on Solana via x402 micropayments.
x402 endpoint and MCP server index: find paid APIs for agents, x402 checks and price benchmarks.
