# 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)
Chains accepted (the 402 lists them all, the agent picks one):
- Base mainnet [eip155:8453]
    asset: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
    pay to: 0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73
- Solana mainnet [solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp]
    asset: USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
    pay to: 7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi
    The facilitator sponsors the transaction fee, so no SOL is needed to pay.
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.
- POST /mcp - Model Context Protocol server (stateless, 2026-07-28 and 2025-11-25). Free tools: sentinel_network_overview, sentinel_node_lookup, sentinel_top_nodes.

## 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. Also returns chain_registry: lifetime node registrations on the Sentinel chain versus nodes currently in active status, counted directly on-chain — the gap shows how much of the advertised network is actually alive. 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.