{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentWhitelist (agentwhitelist.com) API",
    "version": "3.1.0",
    "description": "One hidden npm postinstall script can dump production keys in seconds. Lock Cursor, Claude, and CI configs to verified SHA-512 hashes and SLSA provenance."
  },
  "servers": [
    {
      "url": "https://agentwhitelist.com",
      "description": "agentwhitelist.com production edge"
    }
  ],
  "x-spoke-host": "agentwhitelist.com",
  "x-x402-protocol": {
    "network": "eip155:8453",
    "asset": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "requestHeaders": [
      "X-PAYMENT",
      "PAYMENT-SIGNATURE"
    ],
    "responseHeaders": [
      "PAYMENT-REQUIRED",
      "X-Payment-Response"
    ],
    "sandboxAuthHeader": "Authorization: Bearer shinn_sbx_..."
  },
  "security": [
    {
      "BearerSandboxAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerSandboxAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "shinn_sbx_...",
        "description": "Sandbox or provisioned spoke token passed via `Authorization: Bearer shinn_sbx_...`. Mint a free sandbox token at `/sandbox`."
      },
      "X402PaymentHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PAYMENT",
        "description": "Base Mainnet (eip155:8453) USDC signed x402 payment payload paired with `PAYMENT-REQUIRED` headers."
      }
    },
    "headers": {
      "PAYMENT-REQUIRED": {
        "description": "Base64/JSON x402 payment requirement returned with HTTP 402.",
        "schema": {
          "type": "string"
        }
      },
      "X-Payment-Response": {
        "description": "Signed x402 settlement receipt returned on paid HTTP 200 responses.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "X402Challenge": {
        "type": "object",
        "required": [
          "error",
          "network",
          "asset",
          "amount_usdc"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "payment_required"
          },
          "network": {
            "type": "string",
            "example": "eip155:8453"
          },
          "asset": {
            "type": "string",
            "example": "USDC"
          },
          "amount_usdc": {
            "type": "string",
            "example": "0.01"
          },
          "pay_to": {
            "type": "string"
          },
          "sandbox_url": {
            "type": "string",
            "example": "https://agentwhitelist.com/sandbox"
          }
        }
      },
      "CalculatorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "matches": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "CompareResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "DossierResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "BenchmarkResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "MeterPreviewResponse": {
        "type": "object",
        "required": [
          "ok",
          "host",
          "auth_mode",
          "x402"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "auth_mode": {
            "type": "string",
            "example": "Authorization: Bearer shinn_sbx_..."
          },
          "remaining_credits": {
            "type": "integer"
          },
          "x402": {
            "$ref": "#/components/schemas/X402Challenge"
          }
        }
      },
      "TrustVerdictResponse": {
        "type": "object",
        "properties": {
          "verdict": {
            "type": "string"
          },
          "trust_score": {
            "type": "number"
          },
          "wash_score": {
            "type": "number"
          },
          "sha512": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Live D1 health status",
        "description": "Returns live Worker & D1 health status.",
        "responses": {
          "200": {
            "description": "Health JSON"
          }
        }
      }
    },
    "/api-docs": {
      "get": {
        "operationId": "getApiDocs",
        "summary": "Interactive Developer SDK & OpenAPI Docs Hub",
        "description": "Mobile-safe SDK quickstart page with cURL, Python, TypeScript, and Claude/Cursor MCP snippets.",
        "responses": {
          "200": {
            "description": "Interactive HTML developer docs"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "summary": "OpenAPI 3.1.0 machine specification",
        "description": "Returns live OpenAPI 3.1.0 JSON tailored to this hostname.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1.0 JSON"
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "operationId": "getWellKnownMcp",
        "summary": "MCP JSON-RPC discovery manifest",
        "description": "Returns Claude Desktop / Cursor MCP transport metadata and exposed tools.",
        "responses": {
          "200": {
            "description": "MCP manifest JSON"
          }
        }
      }
    },
    "/api/v1/calculator": {
      "get": {
        "operationId": "getV1Calculator",
        "summary": "Live D1 trust/wash/compliance search and calculator",
        "description": "Scores MCP server supply-chain risk and wash-trading probability from live D1 tables.",
        "security": [
          {
            "BearerSandboxAuth": []
          },
          {
            "X402PaymentHeader": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "html"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculator JSON or HTML",
            "headers": {
              "X-Payment-Response": {
                "$ref": "#/components/headers/X-Payment-Response"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculatorResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 Base USDC payment challenge",
            "headers": {
              "PAYMENT-REQUIRED": {
                "$ref": "#/components/headers/PAYMENT-REQUIRED"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Challenge"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/compare": {
      "get": {
        "operationId": "getV1Compare",
        "summary": "Programmatic competitor comparison matrix JSON",
        "description": "Compares live trust verification & wash-filter coverage against alternative scanners.",
        "security": [
          {
            "BearerSandboxAuth": []
          },
          {
            "X402PaymentHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Compare JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompareResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 Base USDC payment challenge",
            "headers": {
              "PAYMENT-REQUIRED": {
                "$ref": "#/components/headers/PAYMENT-REQUIRED"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Challenge"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dossiers": {
      "get": {
        "operationId": "getV1Dossiers",
        "summary": "Structured MCP / agent security dossiers",
        "description": "Returns forensic verification dossiers, drift receipts, and lockfile hashes.",
        "security": [
          {
            "BearerSandboxAuth": []
          },
          {
            "X402PaymentHeader": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dossiers JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DossierResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 Base USDC payment challenge",
            "headers": {
              "PAYMENT-REQUIRED": {
                "$ref": "#/components/headers/PAYMENT-REQUIRED"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Challenge"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/benchmarks": {
      "get": {
        "operationId": "getV1Benchmarks",
        "summary": "Live supply-chain & wash-filter benchmarks",
        "description": "Returns statistical benchmarks across audited MCP packages and wash-trade telemetry.",
        "security": [
          {
            "BearerSandboxAuth": []
          },
          {
            "X402PaymentHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Benchmarks JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BenchmarkResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 Base USDC payment challenge",
            "headers": {
              "PAYMENT-REQUIRED": {
                "$ref": "#/components/headers/PAYMENT-REQUIRED"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Challenge"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/meter-preview": {
      "get": {
        "operationId": "getV1MeterPreview",
        "summary": "Sandbox token & x402 Base USDC metering preview",
        "description": "Checks `Authorization: Bearer shinn_sbx_...` quota and returns x402 Base USDC (`eip155:8453`) header metadata.",
        "security": [
          {
            "BearerSandboxAuth": []
          },
          {
            "X402PaymentHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "Metering preview JSON",
            "headers": {
              "X-Payment-Response": {
                "$ref": "#/components/headers/X-Payment-Response"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterPreviewResponse"
                }
              }
            }
          },
          "402": {
            "description": "x402 Base USDC challenge",
            "headers": {
              "PAYMENT-REQUIRED": {
                "$ref": "#/components/headers/PAYMENT-REQUIRED"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402Challenge"
                }
              }
            }
          }
        }
      }
    },
    "/v1/check": {
      "get": {
        "operationId": "getLegacyV1Check",
        "summary": "Check agent or MCP verdict",
        "description": "Returns trust verdict, wash-score, and SHA-512 digest for an agent or MCP server.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verdict JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrustVerdictResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/lockfile": {
      "post": {
        "operationId": "postV1Lockfile",
        "summary": "Compile SHA-512 lockfile",
        "description": "Scans submitted `mcp.json` configuration and returns a pinned SHA-512 lockfile.",
        "responses": {
          "200": {
            "description": "Lockfile JSON"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "postMcpRpc",
        "summary": "MCP JSON-RPC endpoint",
        "description": "Streamable HTTP JSON-RPC endpoint for MCP clients.",
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    },
    "/api/privacy/consent": {
      "get": {
        "operationId": "getPrivacyConsent",
        "summary": "GDPR consent policy",
        "description": "Returns consent policy metadata.",
        "responses": {
          "200": {
            "description": "Policy JSON"
          }
        }
      },
      "post": {
        "operationId": "savePrivacyConsent",
        "summary": "Record GDPR consent choice",
        "description": "Persists privacy consent selection.",
        "responses": {
          "200": {
            "description": "Saved JSON"
          }
        }
      }
    },
    "/api/panopticon/status": {
      "get": {
        "operationId": "getPanopticonStatus",
        "summary": "Panopticon hook status",
        "description": "Returns Panopticon telemetry hook status.",
        "responses": {
          "200": {
            "description": "Status JSON"
          }
        }
      }
    }
  }
}