# Node Scorecard API

> Independent measurement and scoring of the Sentinel dVPN network. Pay per call in USDC over x402 — no account, no API key, no signup.

Base URL: https://nodescorecard.xyz

## Payment
Protocol: x402 (version 2)
Network: eip155:8453 (Base mainnet)
Asset: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Pay to: 0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73
Facilitator: https://facilitator.payai.network
No account, no API key, no signup. Requests that fail are never charged.

## Free endpoints
- GET / - This page (HTML for browsers, JSON for agents).
- GET /manifest - This document.
- GET /llms.txt - Plain-text summary.
- GET /scorecard/health - Liveness and configuration.

## Paid endpoints
- GET /scorecard/network-stats - $0.010 - Network-wide Sentinel dVPN health report: ASN concentration and HHI index, verified residential share, protocol mix, censorship-resistance mix, country distribution, SLA speed percentiles, P2P price percentiles. No parameters.
- GET /scorecard/recommend - $0.010 - Ranked node recommendations for a stated need, diversified across ASNs and countries so the result is not concentrated on one provider. Returns one recommendation plus three alternatives.
    need (string): Free text describing the requirement, e.g. "privacy residential" or "speed europe". Matched case-insensitively.
    country (string): Restrict candidates to a single country, exact name, case-insensitive, e.g. "Germany".
- GET /scorecard/nodes - $0.005 - Snapshot of nodes with composite score, reliability, uptime, SLA speed, price, ASN, jurisdiction freedom and residential verification. Returns active nodes by default.
    all (string, one of: 1): Set to 1 to return every tracked node instead of only the active ones.
- GET /scorecard/nodes/top - $0.005 - Top nodes by composite score, with filtering and anti-concentration controls.
    n (integer, default 5, range 1-50): How many nodes to return. Values outside the range are clamped.
    max_per_asn (integer, default 2, min 1): Anti-concentration cap: maximum number of returned nodes sharing one ASN.
    min_score (number, default 0): Minimum composite score, 0 to 100.
    country (string): Exact country name, case-insensitive.
    protocol (string, one of: v2ray | wireguard | xray | openvpn | hysteria2 | amneziawg): Filter by protocol. Also matches multi-protocol nodes that advertise it.
    sla_only (string, one of: true): Set to true to return only nodes that passed the SLA speed test.
- GET /scorecard/node/:address - $0.003 - Full scorecard for a single node, addressed by its sentnode1... bech32 address. No query parameters.

## Data
Independent collector polling every active node API directly, plus on-chain state. Not self-reported by node operators.
Refresh: hourly. Responses cached 600s.