{"openapi":"3.1.0","info":{"title":"Wicked Registry","version":"0.1.0","description":"A reliability-scored trust layer for x402/MCP tool marketplaces. Every score component comes from a real HTTP call at check time — no fabricated or estimated data.","contact":{"url":"https://registry.wickedapi.com/"}},"servers":[{"url":"https://registry.wickedapi.com"}],"tags":[{"name":"tools","description":"Public tool registry and scoring"},{"name":"admin","description":"Admin-only moderation, gated by x-admin-api-key"},{"name":"meta","description":"Liveness and discovery"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"AdminApiKeyAuth":{"type":"apiKey","in":"header","name":"x-admin-api-key"}},"schemas":{"Tool":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerWallet":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"protocol":{"type":"string","enum":["x402","mcp","rest"]},"category":{"type":"string"},"description":{"type":"string"},"schemaUrl":{"type":"string","format":"uri","nullable":true},"source":{"type":"string","enum":["self_submitted","imported_bazaar","imported_agent402","imported_mcp"]},"status":{"type":"string","enum":["active","suspended"]},"submittedAt":{"type":"string","format":"date-time"},"score":{"oneOf":[{"type":"string","const":"insufficient data"},{"type":"object","properties":{"computedAt":{"type":"string","format":"date-time"},"uptimePct24h":{"type":"number","nullable":true},"uptimePct7d":{"type":"number","nullable":true},"uptimePct30d":{"type":"number","nullable":true},"avgLatencyMs24h":{"type":"number","nullable":true},"schemaConformancePct":{"type":"number","nullable":true},"compositeScore":{"type":"number","nullable":true},"sampleSize24h":{"type":"integer"}}}]}}},"Score":{"oneOf":[{"type":"string","const":"insufficient data"},{"type":"object","properties":{"computedAt":{"type":"string","format":"date-time"},"uptimePct24h":{"type":"number","nullable":true},"uptimePct7d":{"type":"number","nullable":true},"uptimePct30d":{"type":"number","nullable":true},"avgLatencyMs24h":{"type":"number","nullable":true},"schemaConformancePct":{"type":"number","nullable":true},"compositeScore":{"type":"number","nullable":true},"sampleSize24h":{"type":"integer"}}}]},"Error":{"type":"object","properties":{"error":{"type":"string"},"source":{"type":"string"}},"required":["error","source"]}}},"paths":{"/tools/register":{"post":{"tags":["tools"],"summary":"Register a tool you own","description":"Wallet-signature-authenticated. Verifies a real ECDSA signature recovery over a message binding name + endpointUrl + timestamp — never trusts a client-asserted wallet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","endpointUrl","protocol","category","description","ownerWallet","signature","timestamp"],"properties":{"name":{"type":"string","maxLength":200},"endpointUrl":{"type":"string","format":"uri"},"protocol":{"type":"string","enum":["x402","mcp","rest"]},"category":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":2000},"schemaUrl":{"type":"string","format":"uri"},"ownerWallet":{"type":"string","description":"0x wallet address"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]+$"},"timestamp":{"type":"string","format":"date-time","description":"Must be within 10 minutes of the request"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerWallet":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"protocol":{"type":"string","enum":["x402","mcp","rest"]},"category":{"type":"string"},"description":{"type":"string"},"schemaUrl":{"type":"string","format":"uri","nullable":true},"source":{"type":"string","enum":["self_submitted","imported_bazaar","imported_agent402","imported_mcp"]},"status":{"type":"string","enum":["active","suspended"]},"submittedAt":{"type":"string","format":"date-time"},"score":{"oneOf":[{"type":"string","const":"insufficient data"},{"type":"object","properties":{"computedAt":{"type":"string","format":"date-time"},"uptimePct24h":{"type":"number","nullable":true},"uptimePct7d":{"type":"number","nullable":true},"uptimePct30d":{"type":"number","nullable":true},"avgLatencyMs24h":{"type":"number","nullable":true},"schemaConformancePct":{"type":"number","nullable":true},"compositeScore":{"type":"number","nullable":true},"sampleSize24h":{"type":"integer"}}}]}}},"meta":{"type":"object","additionalProperties":true}},"required":["data","meta"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"source":{"type":"string"}},"required":["error","source"]}}}},"401":{"description":"Signature does not match claimed wallet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"source":{"type":"string"}},"required":["error","source"]}}}}}}},"/tools":{"get":{"tags":["tools"],"summary":"List and search scored tools","description":"Free with a valid x-api-key. Otherwise a real x402 402 payment challenge (scheme exact, USDC).","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"protocol","in":"query","schema":{"type":"string","enum":["x402","mcp","rest"]}},{"name":"min_score","in":"query","schema":{"type":"number","minimum":0,"maximum":100}},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","latency","recency"],"default":"score"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerWallet":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"protocol":{"type":"string","enum":["x402","mcp","rest"]},"category":{"type":"string"},"description":{"type":"string"},"schemaUrl":{"type":"string","format":"uri","nullable":true},"source":{"type":"string","enum":["self_submitted","imported_bazaar","imported_agent402","imported_mcp"]},"status":{"type":"string","enum":["active","suspended"]},"submittedAt":{"type":"string","format":"date-time"},"score":{"oneOf":[{"type":"string","const":"insufficient data"},{"type":"object","properties":{"computedAt":{"type":"string","format":"date-time"},"uptimePct24h":{"type":"number","nullable":true},"uptimePct7d":{"type":"number","nullable":true},"uptimePct30d":{"type":"number","nullable":true},"avgLatencyMs24h":{"type":"number","nullable":true},"schemaConformancePct":{"type":"number","nullable":true},"compositeScore":{"type":"number","nullable":true},"sampleSize24h":{"type":"integer"}}}]}}}},"meta":{"type":"object","additionalProperties":true}},"required":["data","meta"]}}}},"402":{"description":"Payment required (x402)","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 PaymentRequirements"}}}}}},"/tools/{id}":{"get":{"tags":["tools"],"summary":"Get one tool's full score breakdown and check history","description":"Free with a valid x-api-key. Otherwise a real x402 402 payment challenge.","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerWallet":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"protocol":{"type":"string","enum":["x402","mcp","rest"]},"category":{"type":"string"},"description":{"type":"string"},"schemaUrl":{"type":"string","format":"uri","nullable":true},"source":{"type":"string","enum":["self_submitted","imported_bazaar","imported_agent402","imported_mcp"]},"status":{"type":"string","enum":["active","suspended"]},"submittedAt":{"type":"string","format":"date-time"},"score":{"oneOf":[{"type":"string","const":"insufficient data"},{"type":"object","properties":{"computedAt":{"type":"string","format":"date-time"},"uptimePct24h":{"type":"number","nullable":true},"uptimePct7d":{"type":"number","nullable":true},"uptimePct30d":{"type":"number","nullable":true},"avgLatencyMs24h":{"type":"number","nullable":true},"schemaConformancePct":{"type":"number","nullable":true},"compositeScore":{"type":"number","nullable":true},"sampleSize24h":{"type":"integer"}}}]}}},"meta":{"type":"object","additionalProperties":true}},"required":["data","meta"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"source":{"type":"string"}},"required":["error","source"]}}}}}}},"/featured-tools":{"get":{"tags":["tools"],"summary":"Top scored active tools","description":"Public, free, no key or payment required. Powers the landing page.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerWallet":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"protocol":{"type":"string","enum":["x402","mcp","rest"]},"category":{"type":"string"},"description":{"type":"string"},"schemaUrl":{"type":"string","format":"uri","nullable":true},"source":{"type":"string","enum":["self_submitted","imported_bazaar","imported_agent402","imported_mcp"]},"status":{"type":"string","enum":["active","suspended"]},"submittedAt":{"type":"string","format":"date-time"},"score":{"oneOf":[{"type":"string","const":"insufficient data"},{"type":"object","properties":{"computedAt":{"type":"string","format":"date-time"},"uptimePct24h":{"type":"number","nullable":true},"uptimePct7d":{"type":"number","nullable":true},"uptimePct30d":{"type":"number","nullable":true},"avgLatencyMs24h":{"type":"number","nullable":true},"schemaConformancePct":{"type":"number","nullable":true},"compositeScore":{"type":"number","nullable":true},"sampleSize24h":{"type":"integer"}}}]}}}},"meta":{"type":"object","additionalProperties":true}},"required":["data","meta"]}}}}}}},"/lookup":{"get":{"tags":["tools"],"summary":"Free lookup of tool ids and headline scores","description":"Public, free, no key or payment. Match by name/URL fragment (q), exact endpoint URL (endpoint) or category. Headline score only; the breakdown and history are on the paid GET /tools/{id}.","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":2}},{"name":"endpoint","in":"query","schema":{"type":"string","format":"uri"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"OK"}}}},"/onboard":{"get":{"tags":["onboarding"],"summary":"Exact message to sign for an API key or a tool registration","description":"Public, free. action=api_key needs wallet; action=register needs name and endpointUrl. The response includes the message, timestamp and a ready-to-fill submit request.","parameters":[{"name":"action","in":"query","schema":{"type":"string","enum":["api_key","register"]}},{"name":"wallet","in":"query","schema":{"type":"string"}},{"name":"name","in":"query","schema":{"type":"string"}},{"name":"endpointUrl","in":"query","schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Missing or invalid parameters"}}}},"/keys":{"post":{"tags":["onboarding"],"summary":"Create a free self-serve API key","description":"Wallet-signature auth over the message from GET /onboard?action=api_key. The key is returned once. Rate-limited per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet","timestamp","signature"],"properties":{"wallet":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]+$"},"label":{"type":"string","maxLength":100}}}}}},"responses":{"201":{"description":"Created"},"401":{"description":"Signature invalid or expired"},"409":{"description":"Wallet is at its active-key limit"}}}},"/keys/self":{"get":{"tags":["onboarding"],"summary":"Metadata and usage for the presented key","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unknown or revoked key"}}},"delete":{"tags":["onboarding"],"summary":"Revoke the presented key","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unknown or revoked key"}}}},"/tools/{id}/badge":{"get":{"tags":["tools"],"summary":"A tool's current composite score","description":"Public, free, no key or payment required, ever — the free growth-loop endpoint tool owners embed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"type":"string","enum":["svg"]},"description":"Omit for JSON; \"svg\" for an embeddable badge image"}],"responses":{"200":{"description":"OK","content":{"application/json":{},"image/svg+xml":{}}},"404":{"description":"Tool not found"}}}},"/tools/{id}/report":{"post":{"tags":["tools"],"summary":"File a complaint about a tool","description":"Public, rate-limited, no auth required. Reviewed manually via the admin endpoints below — never auto-suspends.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reporter","reason"],"properties":{"reporter":{"type":"string","maxLength":200,"description":"Wallet address or best-effort identifier"},"reason":{"type":"string","enum":["downtime","incorrect_response","scam_or_abuse","schema_violation","other"]},"evidence":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Created"},"404":{"description":"Tool not found"}}}},"/admin/tools/import":{"post":{"tags":["admin"],"summary":"Ingest a directory-sourced listing","description":"source: imported_* — no owner signature to verify, ownerWallet is provenance metadata only.","security":[{"AdminApiKeyAuth":[]}],"responses":{"201":{"description":"Created"},"401":{"description":"Missing or invalid x-admin-api-key"}}}},"/admin/tools/{id}":{"patch":{"tags":["admin"],"summary":"Correct a listing's ownerWallet and/or description","security":[{"AdminApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid body"},"401":{"description":"Missing or invalid x-admin-api-key"},"404":{"description":"Tool not found"}}}},"/admin/tools/{id}/suspend":{"post":{"tags":["admin"],"summary":"Suspend a tool","security":[{"AdminApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid x-admin-api-key"},"404":{"description":"Tool not found"}}}},"/admin/reports":{"get":{"tags":["admin"],"summary":"Review queue for filed reports","security":[{"AdminApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","reviewed","dismissed"]}},{"name":"toolId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid x-admin-api-key"}}}},"/admin/reports/{id}/resolve":{"post":{"tags":["admin"],"summary":"Mark a report reviewed or dismissed","security":[{"AdminApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid x-admin-api-key"},"404":{"description":"Report not found"}}}},"/health":{"get":{"tags":["meta"],"summary":"Liveness check","responses":{"200":{"description":"OK"}}}},"/v1/status":{"get":{"tags":["meta"],"summary":"Live endpoint catalog","responses":{"200":{"description":"OK"}}}}}}