{
  "openapi": "3.1.0",
  "info": {
    "title": "Soliscope Reputation API",
    "version": "1.0.0",
    "description": "Creator reputation for pump.fun launches — block/caution/no_flags/unknown verdicts from tracked on-chain outcomes. Verdicts are Soliscope's default skip policy applied to detected signals, not predictions. Docs: https://soliscope.io/docs",
    "contact": { "email": "hello@soliscope.io" }
  },
  "servers": [{ "url": "https://api.soliscope.io" }],
  "security": [{ "apiKey": [] }],
  "paths": {
    "/v1/reputation/{wallet}": {
      "get": {
        "summary": "Deployer or funder wallet reputation",
        "operationId": "getReputation",
        "parameters": [
          { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Base58 Solana address — deployer or funder; the funder chain is resolved internally." }
        ],
        "responses": {
          "200": {
            "description": "Reputation verdict. Free tier returns the verdict layer only; Builder+ adds role, deployer, and funder evidence blocks.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReputationResponse" } } }
          },
          "400": { "description": "Invalid Solana address." },
          "401": { "description": "Missing or invalid X-API-Key." },
          "403": { "description": "Key revoked." },
          "429": { "description": "Rate limit or monthly quota exceeded." }
        }
      }
    },
    "/v1/launch/{mint}/risk": {
      "get": {
        "summary": "Launch risk by token mint",
        "operationId": "getLaunchRisk",
        "parameters": [
          { "name": "mint", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Base58 token mint address." }
        ],
        "responses": {
          "200": {
            "description": "Verdict plus launch-level flags. status=analysing while enrichment runs (seconds after launch).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchRiskResponse" } } }
          },
          "400": { "description": "Invalid mint address." },
          "401": { "description": "Missing or invalid X-API-Key." },
          "403": { "description": "Key revoked." },
          "404": { "description": "Launch not tracked." },
          "429": { "description": "Rate limit or monthly quota exceeded." }
        }
      }
    },
    "/v1/status": {
      "get": {
        "summary": "Public uptime and latency",
        "operationId": "getStatus",
        "security": [],
        "responses": {
          "200": {
            "description": "Self-measured service status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "uptimeSeconds": { "type": "integer" },
                    "latency": {
                      "type": "object",
                      "properties": {
                        "p50Ms": { "type": ["integer", "null"] },
                        "p95Ms": { "type": ["integer", "null"] },
                        "sampled": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "schemas": {
      "Verdict": {
        "type": "string",
        "enum": ["block", "caution", "no_flags", "unknown"],
        "description": "Soliscope's default skip policy applied to the signals. no_flags claims detection coverage, never safety."
      },
      "ReasonCode": {
        "type": "string",
        "enum": [
          "deployer_serial_rugger",
          "deployer_repeat_rugger",
          "deployer_rug_rate_extreme",
          "deployer_prior_rug",
          "token_risk_flags",
          "deployer_clean_history",
          "insufficient_history"
        ],
        "description": "Stable machine-readable codes. `deployer_serial_rugger` fires at rugCount >= 3; `deployer_repeat_rugger` fires at exactly 2 (both cause a block). Split 2026-08-03 so the reason code semantics match the website chip and the /launch/:mint/signals endpoint. Retired 2026-07 after de-confounded audit: funder_confirmed_rug_factory, funder_seeded_ruggers, funder_high_volume — no longer emitted."
      },
      "DeployerStats": {
        "type": ["object", "null"],
        "properties": {
          "launches": { "type": "integer" },
          "rugs": { "type": "integer" },
          "resolved": { "type": "integer", "description": "Launches with a known outcome." },
          "graduated": { "type": "integer" },
          "rugRate": { "type": ["number", "null"] }
        }
      },
      "FunderStats": {
        "type": ["object", "null"],
        "properties": {
          "address": { "type": "string" },
          "deployersSeeded": { "type": "integer", "description": "Distinct deployers funded by this wallet." },
          "deployersRugged": { "type": "integer", "description": "Distinct funded deployers with a confirmed rug." }
        }
      },
      "ReputationResponse": {
        "type": "object",
        "required": ["wallet", "verdict", "confidence", "reasons", "dataAsOf"],
        "properties": {
          "wallet": { "type": "string" },
          "verdict": { "$ref": "#/components/schemas/Verdict" },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
          "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonCode" } },
          "dataAsOf": { "type": "string", "format": "date-time" },
          "role": { "type": "string", "enum": ["deployer", "funder", "unknown"], "description": "Builder+ only." },
          "deployer": { "$ref": "#/components/schemas/DeployerStats", "description": "Builder+ only." },
          "funder": { "$ref": "#/components/schemas/FunderStats", "description": "Builder+ only." }
        }
      },
      "LaunchRiskResponse": {
        "type": "object",
        "required": ["mint", "status", "verdict", "confidence", "reasons", "dataAsOf"],
        "properties": {
          "mint": { "type": "string" },
          "status": { "type": "string", "enum": ["analysed", "analysing"] },
          "verdict": { "$ref": "#/components/schemas/Verdict" },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
          "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonCode" } },
          "dataAsOf": { "type": "string", "format": "date-time" },
          "deployerWallet": { "type": "string", "description": "Builder+ only." },
          "deployer": { "$ref": "#/components/schemas/DeployerStats", "description": "Builder+ only." },
          "funder": { "$ref": "#/components/schemas/FunderStats", "description": "Builder+ only." },
          "token": {
            "type": "object",
            "description": "Builder+ only.",
            "properties": {
              "riskLevel": { "type": "string", "enum": ["low", "medium", "high", "extreme"] },
              "outcome": { "type": "string", "enum": ["unknown", "active", "graduated", "rugged", "abandoned"] },
              "isBundled": { "type": "boolean" },
              "sniperCount": { "type": "integer" },
              "holderConcentration": { "type": ["number", "null"] },
              "bondingCurveProgress": { "type": ["number", "null"] },
              "insiderFlag": { "type": "boolean" },
              "smartMoneyFlag": { "type": "boolean" },
              "projectInsiderFlag": { "type": "boolean" }
            }
          }
        }
      }
    }
  }
}