SatRank MCP server

Lightning trust oracle for AI agents on L402. Bitcoin-pure.

[email protected] exposes 3 tools that let any MCP-compatible AI agent (Claude Code, Cursor, Codex, n8n, Claude Desktop) discover L402 endpoints, read their Bayesian trust posterior, and verify Nostr trust assertions offline.

This is the Bitcoin-pure trust layer that sits BEFORE the payment hop. Agents pay with whatever Lightning wallet they're configured with ; SatRank decides what's worth paying for and exposes the offline-verifiable signed oracle output.

What you get with one install

| Tool | What | |---|---| | intent | Category + budget + SLA → ranked L402 candidates with full Bayesian breakdown. Paid 2 sats per call via L402 (your wallet settles the invoice). | | get_endpoint_score | Per-endpoint trust snapshot (sha256 url_hash). Same posteriors + freshness, scoped to one URL. Free. | | verify_assertion | Offline Schnorr verify of a SatRank Nostr trust assertion (kind 30782). No network. Free. |

That's the entire surface. No fulfill proxy, no audit chain — V3 is the Bitcoin-pure trust layer, nothing more.

Install

Claude Code

claude mcp add satrank -- npx -y satrank-mcp

Or via the configuration file (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "satrank": {
      "command": "npx",
      "args": ["-y", "satrank-mcp"]
    }
  }
}

Cursor / Codex / n8n / any MCP client

Same idea — point your MCP client at npx -y satrank-mcp. Stdio transport.

Self-hosted

Set SATRANK_API_BASE to your own SatRank deployment URL. The MCP package is HTTP-only ; it does not talk to Postgres or LND directly.

SATRANK_API_BASE=https://your-host.example npx -y satrank-mcp

Environment

| Var | Required | Default | What | |---|---|---|---| | SATRANK_API_BASE | no | https://satrank.dev | HTTP API the MCP proxies to |

Example agent flow

1. agent → satrank.intent(category="data", budget_sats=20, optimize="latency")
   → returns 3 ranked candidates {url, p_e2e, ci95, stage_posteriors,
     median_latency_ms, price_sats}. Paid 2 sats once via L402.

2. agent → satrank.get_endpoint_score(url_hash="<sha256>")
   → independent verification of one candidate's posterior. Free.

3. agent pays the chosen L402 endpoint with its own wallet.
   SatRank is NOT in the payment path.

4. (optional) agent → satrank.verify_assertion(event=<nostr_kind_30782>)
   → offline Schnorr verify. Useful for caching trust assertions and
     re-checking later without re-querying SatRank.

Multi-call discovery (deposit credits)

The HTTP API also exposes a deposit primitive — pre-pay N sats once, spend across many intent calls without a Lightning round-trip per call. Useful when an agent will make tens or hundreds of discovery calls in a window.

# 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_<id>", invoice: "lnbc...", payment_hash: "..."}

# 2. Pay the BOLT11 invoice with any Lightning wallet.

# 3. Subsequent calls use the deposit as a bearer:
curl -s -X POST https://satrank.dev/api/intent \
  -H 'Authorization: L402 deposit_<id>:<preimage_hex>' \
  -H 'Content-Type: application/json' \
  -d '{"category":"data"}'

# 4. Check remaining balance any time:
curl -s https://satrank.dev/api/deposit/<id>

Lightning-pure stance

SatRank only emits and consumes Lightning sats. No x402, no Base, no EVM. This is doctrine, not configuration.

License & links

• License: MIT
• Homepage: https://satrank.dev
• Source: https://github.com/proofoftrust21/satrank