{"openapi":"3.1.0","info":{"title":"Node Scorecard API","version":"1.0.0","description":"Independent measurement and scoring of the Sentinel dVPN network. Paid endpoints use the x402 protocol: no account, no API key, no signup. Requests that fail (HTTP >= 400) are never settled."},"servers":[{"url":"https://nodescorecard.xyz"}],"paths":{"/scorecard/network-stats":{"get":{"summary":"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","description":"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.","operationId":"scorecard_network_stats","parameters":[],"responses":{"200":{"description":"Success. Returned only after x402 settlement.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. See the PAYMENT-REQUIRED response header for the x402 payload.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Upstream scorecard feed unavailable. Never settled."}},"x-x402":{"price_usd":0.01,"accepts":[{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","pay_to":"7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi"}],"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"}}},"/scorecard/recommend":{"get":{"summary":"Ranked node recommendations for a stated need, diversified across ASNs and countries so the result is not concentrated on one provider","description":"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.","operationId":"scorecard_recommend","parameters":[{"name":"need","in":"query","required":false,"description":"Free text describing the requirement, e.g. \"privacy residential\" or \"speed europe\". Matched case-insensitively.","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Restrict candidates to a single country, exact name, case-insensitive, e.g. \"Germany\".","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Returned only after x402 settlement.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. See the PAYMENT-REQUIRED response header for the x402 payload.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Upstream scorecard feed unavailable. Never settled."}},"x-x402":{"price_usd":0.01,"accepts":[{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","pay_to":"7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi"}],"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"}}},"/scorecard/nodes":{"get":{"summary":"Snapshot of nodes with composite score, reliability, uptime, SLA speed, price, ASN, jurisdiction freedom and residential verification","description":"Snapshot of nodes with composite score, reliability, uptime, SLA speed, price, ASN, jurisdiction freedom and residential verification. Returns active nodes by default.","operationId":"scorecard_nodes","parameters":[{"name":"all","in":"query","required":false,"description":"Set to 1 to return every tracked node instead of only the active ones.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Success. Returned only after x402 settlement.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. See the PAYMENT-REQUIRED response header for the x402 payload.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Upstream scorecard feed unavailable. Never settled."}},"x-x402":{"price_usd":0.005,"accepts":[{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","pay_to":"7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi"}],"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"}}},"/scorecard/nodes/top":{"get":{"summary":"Top nodes by composite score, with filtering and anti-concentration controls","description":"Top nodes by composite score, with filtering and anti-concentration controls.","operationId":"scorecard_nodes_top","parameters":[{"name":"n","in":"query","required":false,"description":"How many nodes to return. Values outside the range are clamped.","schema":{"type":"integer","default":5,"minimum":1,"maximum":50}},{"name":"max_per_asn","in":"query","required":false,"description":"Anti-concentration cap: maximum number of returned nodes sharing one ASN.","schema":{"type":"integer","default":2,"minimum":1}},{"name":"min_score","in":"query","required":false,"description":"Minimum composite score, 0 to 100.","schema":{"type":"number","default":0}},{"name":"country","in":"query","required":false,"description":"Exact country name, case-insensitive.","schema":{"type":"string"}},{"name":"protocol","in":"query","required":false,"description":"Filter by protocol. Also matches multi-protocol nodes that advertise it.","schema":{"type":"string","enum":["v2ray","wireguard","xray","openvpn","hysteria2","amneziawg"]}},{"name":"sla_only","in":"query","required":false,"description":"Set to true to return only nodes that passed the SLA speed test.","schema":{"type":"string","enum":["true"]}}],"responses":{"200":{"description":"Success. Returned only after x402 settlement.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. See the PAYMENT-REQUIRED response header for the x402 payload.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Upstream scorecard feed unavailable. Never settled."}},"x-x402":{"price_usd":0.005,"accepts":[{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","pay_to":"7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi"}],"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"}}},"/scorecard/node/{address}":{"get":{"summary":"Full scorecard for a single node, addressed by its sentnode1","description":"Full scorecard for a single node, addressed by its sentnode1... bech32 address. No query parameters.","operationId":"scorecard_node_address","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Returned only after x402 settlement.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. See the PAYMENT-REQUIRED response header for the x402 payload.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Upstream scorecard feed unavailable. Never settled."}},"x-x402":{"price_usd":0.003,"accepts":[{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","pay_to":"7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi"}],"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73"}}},"/scorecard/health":{"get":{"summary":"Liveness and configuration.","operationId":"health","responses":{"200":{"description":"Service is up."}}}}}}