SatRank crawls the L402 endpoint ecosystem (l402.directory + RSS + DNS), probes each endpoint across five stages (challenge / invoice / payment / delivery / quality), and maintains a streaming Beta(α,β) posterior per (endpoint, stage). Agents query a category + budget + SLA and get back the top-K candidates with a full Bayesian breakdown.
End-to-end success probability is the product of stage means. Every candidate ships a 95% credibility interval. The oracle's signed Nostr trust assertions (kind 30782) are offline-verifiable — agents cache them once and re-check without a network round-trip.
Full reference: API page · OpenAPI 3.0 spec.
| Route | Auth | What |
|---|---|---|
| POST /api/intent | L402 paid | 2 sats. Returns ranked candidates filtered by category / budget / max_latency_ms / optimize. |
| POST /api/deposit | free | Mint a multi-use deposit macaroon. Pre-pay 10–10000 sats once; spend across many /api/intent calls without a Lightning round-trip per call. 30-day TTL. |
| GET /api/deposit/:id | free | Read remaining balance + activation status of a deposit macaroon. |
| GET /api/services/:url_hash | free | Per-endpoint score snapshot. |
| GET /api/services/categories | free | List active catalogue categories. |
| GET /api/services/best | free | Top-3 per category (5-min cache). |
| GET /api/oracle/budget | free | Last 24h revenue + paid-probe spend. Net budget. |
| GET /health | free | Liveness probe. |
| GET /.well-known/satrank-key | free | Oracle Schnorr pubkey for offline assertion verify. |
Single-shot 2-sat call (server replies 402 with a BOLT11 invoice ; pay it with any LN wallet, replay with the preimage as bearer token):
curl -i -X POST https://satrank.dev/api/intent \
-H 'Content-Type: application/json' \
-d '{"category":"data","budget_sats":20,"optimize":"latency","limit":3}'Multi-call deposit (one payment, ~50 calls at 2 sats each):
# 1. Mint a 100-sat deposit macaroon
curl -s -X POST https://satrank.dev/api/deposit \
-H 'Content-Type: application/json' \
-d '{"sats":100}'
# → returns {macaroon: "deposit_", invoice: "lnbc...", payment_hash: "..."}
# 2. Pay the invoice with any LN wallet (Wallet of Satoshi, Phoenix, …)
# 3. Use the preimage your wallet returns to authenticate /api/intent
curl -s -X POST https://satrank.dev/api/intent \
-H 'Authorization: L402 deposit_<id>:<preimage_hex>' \
-H 'Content-Type: application/json' \
-d '{"category":"finance","limit":3}'
# 4. Check remaining balance any time
curl -s https://satrank.dev/api/deposit/<id> Three tools for any MCP-compatible AI runtime (Claude Code, Cursor, Codex, n8n, Claude Desktop):
| Tool | What |
|---|---|
| intent | Forwards POST /api/intent. Paid via L402. |
| get_endpoint_score | Forwards GET /api/services/:url_hash. Free. |
| verify_assertion | Offline Schnorr verify of a Nostr kind 30782 trust assertion. No network. |
Install in Claude Code:
claude mcp add satrank -- npx -y satrank-mcpSelf-hosters point SATRANK_API_BASE at their own deployment.
For each (endpoint, stage), maintain a Beta(α, β) posterior with α₀ = β₀ = 1 (uniform prior). On every observation:
p_stage = α / (α + β). End-to-end p_e2e = ∏ p_stage. 95% credibility interval via Wilson's closed-form approximation. Ranking by p_e2e (default), latency, or cost — agents pick their objective.
Full technical reference: methodology page — catalog sources, five-stage decomposition, Bayesian update, Wilson interval, ranking filters, L402 paid gate, deposit credit atomicity, Nostr kind 30782, security hardening.
SatRank only emits and consumes Lightning sats. No x402, no Base, no EVM. This is doctrine, not configuration. The trust layer is the same currency the payment layer settles in.