SatRank

Route reliability for Lightning payments. Built for the agentic economy.

SatRank scores the reliability of Lightning endpoints. Before each payment, an agent queries SatRank for a GO/NO-GO decision — one request, one answer, 1 sat.

Getting Started

npm install
npm run dev     # Start development server on :3000

Architecture

routes → controllers → services → repositories → SQLite

Layers:

Routes — Express endpoint definitions
Controllers — Input validation (zod), response formatting
Services — Business logic and orchestration
Repositories — SQLite data access (better-sqlite3)

Manual dependency injection in src/app.ts for testability.

Scoring Algorithm

Composite score 0-100 computed from 5 weighted factors:

Factor	Weight	Description
Volume	25%	Verified transactions, log-normalized
Reputation	30%	Graph centrality + peer trust (BTC/channel). LN+ ratings as bonus (+8 max)
Seniority	15%	Days since first seen, diminishing returns
Regularity	15%	Inverse coefficient of variation of transaction intervals
Diversity	15%	Unique counterparties, log-normalized

Anti-gaming:

Mutual attestation loop detection (A↔B) with 95% penalty
Circular cluster detection (A→B→C→A) with 90% penalty
Extended cycle detection via BFS (A→B→C→D→A, up to 4 hops) with 90% penalty
Minimum 7-day seniority required to attest
Attester score weighting (PageRank-like recursion)
Attestation source concentration penalty

API

Decision API (primary interface for agents)

# GO / NO-GO decision with success probability
curl -X POST http://localhost:3000/api/decide \
  -H "Content-Type: application/json" \
  -d '{"target": "<hash>", "caller": "<your-hash>"}'

# Report transaction outcome (free — no L402)
curl -X POST http://localhost:3000/api/report \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <key>" \
  -d '{"target": "<hash>", "reporter": "<your-hash>", "outcome": "success"}'

# Agent profile with reports, uptime, rank
curl http://localhost:3000/api/profile/<hash>

Score & Verdict API

curl http://localhost:3000/api/agent/<hash>/verdict
# Returns: SAFE / RISKY / UNKNOWN with confidence, flags, risk profile

Batch Verdicts

curl -X POST http://localhost:3000/api/verdicts \
  -H "Content-Type: application/json" \
  -d '{"hashes": ["abc123...", "def456..."]}'

Agent Score

curl http://localhost:3000/api/agent/<hash>
# Returns: score, components, evidence, delta, alerts

Score History

curl http://localhost:3000/api/agent/<hash>/history?limit=10

Received Attestations

curl http://localhost:3000/api/agent/<hash>/attestations?limit=20

Leaderboard

curl http://localhost:3000/api/agents/top?limit=20&sort_by=score

Top Movers

curl http://localhost:3000/api/agents/movers

Search by Alias

curl http://localhost:3000/api/agents/search?alias=atlas

Submit Attestation (free — no L402)

curl -X POST http://localhost:3000/api/attestations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-key>" \
  -d '{"txId": "...", "attesterHash": "...", "subjectHash": "...", "score": 85, "category": "successful_transaction"}'

Health & Stats

curl http://localhost:3000/api/health
curl http://localhost:3000/api/stats

MCP Server

SatRank exposes an MCP (Model Context Protocol) server for agent-native access via stdio. 11 tools covering trust decisions, scoring, search, and reporting.

Install in Claude Code

claude mcp add satrank -- npx tsx src/mcp/server.ts

Or with environment variables:

claude mcp add satrank -e DB_PATH=./data/satrank.db -e SATRANK_API_KEY=<key> -- npx tsx src/mcp/server.ts

Install in Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "satrank": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/satrank",
      "env": {
        "DB_PATH": "./data/satrank.db",
        "SATRANK_API_KEY": "your-api-key"
      }
    }
  }
}

Available tools (11)

Tool	Description
`decide`	GO/NO-GO with success probability — the primary pre-transaction tool
`report`	Report outcome (success/failure/timeout) — requires API key
`get_profile`	Full agent profile with reports, uptime, rank, evidence
`get_agent_score`	Detailed trust score with components and evidence
`get_verdict`	SAFE/RISKY/UNKNOWN with risk profile and pathfinding
`get_batch_verdicts`	Batch verdict for up to 100 agents
`get_top_agents`	Leaderboard ranked by score
`search_agents`	Search by alias (partial match)
`get_network_stats`	Global network statistics
`get_top_movers`	Agents with biggest 7-day score changes
`submit_attestation`	Submit a trust attestation — requires API key

Run manually

npm run mcp        # Development
npm run mcp:prod   # Production

SDK

npm install @satrank/sdk

import { SatRankClient } from '@satrank/sdk';

const client = new SatRankClient('http://localhost:3000');

// Full cycle in one line: decide → pay → report
const result = await client.transact('<target-hash>', '<your-hash>', async () => {
  const payment = await myWallet.pay(invoice);
  return { success: payment.ok, preimage: payment.preimage, paymentHash: payment.hash };
});
// result.paid, result.decision.go, result.report.weight

// Or step by step
const decision = await client.decide({ target: '<hash>', caller: '<your-hash>' });
const profile = await client.getProfile('<hash>');
const verdict = await client.getVerdict('<hash>');

Nostr Integration

SatRank publishes trust scores for Lightning nodes as NIP-85 Trusted Assertions (kind 30382).

What's published: composite score (0-100), verdict (SAFE/RISKY/UNKNOWN), reachability, survival prediction, and 5 scoring components for ~3,900 nodes with score >= 30.

Frequency: every 6 hours.

Event format:

{
  "kind": 30382,
  "tags": [
    ["d", "<lightning_pubkey>"],
    ["n", "lightning"],
    ["alias", "Kraken"],
    ["score", "94"],
    ["verdict", "SAFE"],
    ["reachable", "true"],
    ["survival", "stable"],
    ["volume", "100"],
    ["reputation", "79"],
    ["seniority", "87"],
    ["regularity", "100"],
    ["diversity", "100"]
  ],
  "content": ""
}

Query assertions from any Nostr client:

["REQ", "satrank", {"kinds": [30382], "authors": ["<SATRANK_NOSTR_PUBKEY>"]}]

Why free? Global scores are the trailer. The personalized /api/decide (pathfinding from YOUR position, survival, P_empirical) is the film — 1 sat via L402.

Tech Stack

TypeScript strict mode
Express — REST API
better-sqlite3 — Embedded database, WAL mode
zod — Input validation
pino — Structured logging
helmet — Security headers
express-rate-limit — Abuse protection

Scripts

Script	Description
`npm run dev`	Development with hot reload (tsx watch)
`npm run build`	TypeScript compilation
`npm start`	Production
`npm test`	Tests (vitest)
`npm run lint`	TypeScript check
`npm run crawl`	Observer Protocol crawler
`npm run crawl:cron`	Crawler en mode cron
`npm run mcp`	MCP server (dev)
`npm run mcp:prod`	MCP server (production)
`npm run purge`	Purge stale data
`npm run backup`	Database backup
`npm run rollback`	Database rollback
`npm run calibrate`	Scoring calibration report
`npm run demo`	Attestation demo script
`npm run sdk:build`	Build TypeScript SDK

Roadmap

Decision API — GO/NO-GO with success probability, outcome reports, agent profiles
Personalized pathfinding — real-time route from caller to target via LND QueryRoutes
Aperture integration (L402 reverse proxy) — monetize queries in sats
Observer Protocol crawler — automatic on-chain data ingestion
Lightning graph crawler — channel topology and capacity via LND node
Route probe crawler — reachability testing for indexed nodes
TypeScript SDK for agents (@satrank/sdk)
Verdict API — SAFE/RISKY/UNKNOWN binary decision
MCP server — agent-native access via stdio
Auto-indexation — unknown pubkeys indexed on demand
4tress connector — verified attestations
Trust network visualization dashboard

Vision

SatRank is the reliability check before every Lightning payment. 66% of the network is phantom nodes — we tell you which endpoints are alive.

SatRank

SatRank

Getting Started

Architecture

Scoring Algorithm

API

Decision API (primary interface for agents)

Score & Verdict API

Batch Verdicts

Agent Score

Score History

Received Attestations

Leaderboard

Top Movers

Search by Alias

Submit Attestation (free — no L402)

Health & Stats

MCP Server

Install in Claude Code

Install in Cursor / VS Code

Available tools (11)

Run manually

SDK

Nostr Integration

Tech Stack

Scripts

Roadmap

Vision

Resources

Latest Blog Posts

MCP directory API