{"openapi":"3.0.3","info":{"title":"Protocol Health Oracle","version":"1.0.0","description":"Live-scored DeFi protocol health: GitHub activity trend, TVL trend, and on-chain treasury signals, computed from real data at refresh time — never fabricated. For builders vetting a dependency before integrating it.\n\n**Access — both work on every /v1 endpoint:**\n1. **API key** — `x-api-key` header, free, rate-limited.\n2. **x402 pay-per-call** — no signup: call with no key, get a `402` for $0.001/request on base USDC, pay via an x402 client, get `200` + data.","contact":{"url":"https://protocol-health-oracle.wickedapi.com"},"termsOfService":"https://protocol-health-oracle.wickedapi.com/"},"servers":[{"url":"https://protocol-health-oracle.wickedapi.com","description":"Production"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Free, rate-limited access."}},"schemas":{"Envelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","description":"Endpoint-specific payload."},"meta":{"type":"object","required":["timestamp"],"properties":{"timestamp":{"type":"string","format":"date-time"}},"additionalProperties":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"source":{"type":"string"}}},"X402Challenge":{"type":"object","description":"x402 payment challenge — sign a USDC transferWithAuthorization and retry with an X-PAYMENT header.","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base"},"maxAmountRequired":{"type":"string"},"resource":{"type":"string"},"description":{"type":"string"},"payTo":{"type":"string"},"asset":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"}}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"No valid x-api-key — pay per call via x402 (USDC on Base).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Challenge"}}}},"RateLimited":{"description":"Rate limit exceeded (keyed access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamError":{"description":"Upstream data error — never fabricated, a real source failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"tags":[{"name":"meta","description":"Health & service catalog"},{"name":"v1","description":"Protocol health data"}],"paths":{"/health":{"get":{"operationId":"get_health","summary":"Liveness check.","description":"Liveness check.","tags":["meta"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[]}},"/v1/status":{"get":{"operationId":"get_v1_status","summary":"Service catalog.","description":"Service catalog.","tags":["v1"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[]}},"/v1/scoreboard":{"get":{"operationId":"get_v1_scoreboard","summary":"Public teaser: protocol name, score, and verdict only (no components/history) across the full tracked universe — auto-ingested from DefiLlama (TVL > $1M) plus curated protocols.","description":"Public teaser: protocol name, score, and verdict only (no components/history) across the full tracked universe — auto-ingested from DefiLlama (TVL > $1M) plus curated protocols.","tags":["v1"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Optional. Rows to return (default 100, max 2000).","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Optional. Pagination offset (default 0).","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Optional. Filter by DefiLlama category, e.g. \"Liquid Staking\".","schema":{"type":"string"}},{"name":"min_tvl","in":"query","required":false,"description":"Optional. Only protocols with TVL >= this USD amount.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[]}},"/v1/protocols":{"get":{"operationId":"get_v1_protocols","summary":"All tracked protocols with their latest health score and verdict.","description":"All tracked protocols with their latest health score and verdict.","tags":["v1"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Optional. Rows to return (default 100, max 2000).","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Optional. Pagination offset (default 0).","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Optional. Filter by DefiLlama category.","schema":{"type":"string"}},{"name":"min_tvl","in":"query","required":false,"description":"Optional. Only protocols with TVL >= this USD amount.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[{"ApiKeyAuth":[]},{}],"x-402":{"scheme":"exact","network":"base","price":"$0.001","maxAmountRequired":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x63EbccD826b874CE988e6498eAabB6Bd47AfC8A4"}},"post":{"operationId":"post_v1_protocols","summary":"Track a new protocol","description":"Track a new protocol. Scored immediately from live GitHub + DeFiLlama data.","tags":["v1"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","github_repo","defillama_slug"],"properties":{"name":{"type":"string","description":"Display name, e.g. \"Lido\"."},"github_repo":{"type":"string","description":"owner/repo, e.g. lidofinance/core."},"defillama_slug":{"type":"string","description":"DeFiLlama protocol slug, e.g. lido."},"chain":{"type":"string","description":"Optional. Default \"ethereum\"."},"treasury_address":{"type":"string","description":"Optional. On-chain treasury address to score (Etherscan balance)."}}}}}},"security":[{"ApiKeyAuth":[]},{}],"x-402":{"scheme":"exact","network":"base","price":"$0.001","maxAmountRequired":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x63EbccD826b874CE988e6498eAabB6Bd47AfC8A4"}}},"/v1/health/{slug}":{"get":{"operationId":"get_v1_health_slug","summary":"Latest health score for one protocol: components (GitHub activity, TVL trend, treasury), source details, and score history.","description":"Latest health score for one protocol: components (GitHub activity, TVL trend, treasury), source details, and score history.","tags":["v1"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Required (path). The protocol's defillama_slug, e.g. lido.","schema":{"type":"string"}},{"name":"history","in":"query","required":false,"description":"Optional. Number of historical scores to include (default 10, max 100).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[{"ApiKeyAuth":[]},{}],"x-402":{"scheme":"exact","network":"base","price":"$0.001","maxAmountRequired":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x63EbccD826b874CE988e6498eAabB6Bd47AfC8A4"}}},"/v1/refresh":{"post":{"operationId":"post_v1_refresh","summary":"Force an immediate live re-score of all tracked protocols.","description":"Force an immediate live re-score of all tracked protocols.","tags":["v1"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[{"ApiKeyAuth":[]},{}],"x-402":{"scheme":"exact","network":"base","price":"$0.001","maxAmountRequired":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x63EbccD826b874CE988e6498eAabB6Bd47AfC8A4"}}},"/v1/ingest":{"post":{"operationId":"post_v1_ingest","summary":"Force an immediate sync of the tracked-protocol universe from DefiLlama (TVL > $1M)","description":"Force an immediate sync of the tracked-protocol universe from DefiLlama (TVL > $1M). Runs automatically once/day; use this to trigger it on demand.","tags":["v1"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}},"security":[{"ApiKeyAuth":[]},{}],"x-402":{"scheme":"exact","network":"base","price":"$0.001","maxAmountRequired":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x63EbccD826b874CE988e6498eAabB6Bd47AfC8A4"}}}}}