{
  "openapi": "3.1.0",
  "info": {
    "title": "Cover Raccoon API",
    "version": "1",
    "description": "DeFi cover (insurance) index and analyses. Read-only. Free: the catalog of scored analyses, the coverage-gap check, the response schema, ready-to-sign purchase quotes, purchase confirmation and the embeddable covered badge. Paid per-use via x402 (USDC on Base or Polygon): only the full analysis of one cover. Both the free check and the paid full analysis carry a signed attestation for offline provenance verification; the signer address is published in /.well-known/x402.json's attestation.signer field.",
    "contact": {
      "url": "https://coverraccoon.com"
    }
  },
  "servers": [{ "url": "https://coverraccoon.com" }],
  "paths": {
    "/api/cover/v1/analyses": {
      "get": {
        "operationId": "coverAnalyses",
        "summary": "Catalog of DeFi cover analyses. Free.",
        "description": "Free catalog of all cover analyses: Raccoon Score + band, covered protocol, audience (retail = protects the buyer, team = protects the buyer's users), coverage-gap counts, red flags, cheapest annual premium, analysis date. Discovery for agents: the provider and product slugs used by every other endpoint come from here.",
        "responses": {
          "200": { "description": "{ apiVersion, count, disclaimer, analyses[] }" }
        }
      }
    },
    "/api/cover/v1/analyses/{provider}/{product}": {
      "get": {
        "operationId": "coverAnalysis",
        "summary": "Full DeFi cover analysis for one product. Paid (x402, default 4.99 USD).",
        "description": "Full structured cover analysis: Raccoon Score across 7 categories, real-risk-fit and coverage gap map (clause by clause), claims process and payout history, capital adequacy, red flags, sources. Free teaser in the 402 body; full via x402. The receipt is shared with the web unlock.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Provider slug, e.g. nexus-mutual."
          },
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Product slug, e.g. uniswap-v3 (from the catalog)."
          }
        ],
        "responses": {
          "200": { "description": "Full structured analysis (after payment or with a valid receipt)." },
          "402": { "description": "Payment required: x402 PaymentRequirements plus a free teaser." },
          "404": { "description": "Unknown cover analysis." }
        }
      }
    },
    "/api/cover/v1/analyses/{provider}/{product}/check": {
      "get": {
        "operationId": "coverCheck",
        "summary": "Decision check for one DeFi cover: coverage gap map + red flags. Free.",
        "description": "Answers 'does this cover actually pay for my risk?' with the clause-by-clause coverage gap map (covered/partial/excluded, with notes) plus all red-flag texts. Carries a signed attestation (offline verifiable) even though it is free. No payment, no receipt, built for high-frequency agent use. Response shape: /api/cover/v1/schema.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "nexus-mutual"
          },
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "uniswap-v3"
          }
        ],
        "responses": {
          "200": { "description": "The signed coverage gap map + red flags." },
          "404": { "description": "Unknown cover analysis." }
        }
      }
    },
    "/api/cover/v1/schema": {
      "get": {
        "operationId": "coverSchema",
        "summary": "Free response schema of the cover endpoints (check + full).",
        "description": "Placeholder-filled structure of what check and the full analysis return, so agents can evaluate the full analysis before paying for it. Free, cacheable.",
        "responses": {
          "200": { "description": "Schema document with placeholder values." }
        }
      }
    },
    "/api/cover/v1/analyses/{provider}/{product}/buy-quote": {
      "get": {
        "operationId": "coverBuyQuote",
        "summary": "Ready-to-sign purchase transaction for one cover (Nexus CoverBroker, Ethereum mainnet). Free.",
        "description": "Returns buyCoverParams + poolAllocationRequests for the Nexus Mutual CoverBroker contract, including a transparently disclosed broker commission (identical on every product, no influence on scores) and mandatory compliance notices that MUST be surfaced to the end user (cover wording, restricted countries, membership required for claims). The caller signs and submits the transaction themselves; Cover Raccoon never takes custody. Quotes are snapshots, do not cache.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "nexus-mutual"
          },
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "uniswap-v3"
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Cover amount in smallest units of the cover asset (e.g. wei)."
          },
          {
            "name": "period",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 28, "maximum": 365 },
            "description": "Cover period in days."
          },
          {
            "name": "coverAsset",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "enum": [0, 1, 6, 7] },
            "description": "0=ETH (18 decimals), 1=DAI (18 decimals), 6=USDC (6 decimals), 7=cbBTC (8 decimals). Determines the units for the amount parameter below."
          },
          {
            "name": "owner",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Buyer address (receives the cover NFT)."
          }
        ],
        "responses": {
          "200": { "description": "{ chainId: 1, coverBroker: '0xCB2B736652D2dBf7d72e4dB880Cf6B7d99507814' (CoverBroker contract on Ethereum mainnet, a DIFFERENT chain from the Polygon x402 payments elsewhere in this API), asset: { id, symbol, decimals }, buyCoverParams, poolAllocationRequests, commission, compliance }." },
          "400": { "description": "Invalid parameters." },
          "404": { "description": "Unknown or non-purchasable product." }
        }
      }
    },
    "/api/cover/buy-confirm": {
      "post": {
        "operationId": "coverBuyConfirm",
        "summary": "Confirm a cover purchase by transaction hash. Free.",
        "description": "Cover Raccoon fetches the transaction, verifies it is a real buyCover to the Nexus CoverBroker on Ethereum mainnet, decodes the covered amount and logs it (idempotent per tx hash). The verified amount then lifts the buyer wallet's reputation score at reputa.xyz on the next scan (gated behind real activity, capped, farm-resistant because a real premium was paid). Optional but recommended after buying.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["txHash"],
                "properties": {
                  "txHash": { "type": "string", "description": "Hash of the buyCover transaction." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Verified and credited." },
          "422": { "description": "Not a verifiable Nexus cover purchase." },
          "429": { "description": "Rate limited." }
        }
      }
    },
    "/api/cover/v1/market/{provider}/{product}/history": {
      "get": {
        "operationId": "coverMarketHistory",
        "summary": "Capacity and premium history for one product. Free.",
        "description": "Active cover, free capacity and premium over time for one product, oldest first, up to 400 recorded points (change-only: a point exists only when something moved by more than about 1%). Objective on-chain/API data, not an opinion, so unsigned.",
        "parameters": [
          { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "example": "nexus-mutual" },
          { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": "uniswap-v3" }
        ],
        "responses": {
          "200": { "description": "{ apiVersion, note, provider, product, count, points: [{ t, activeUsd, availableUsd, pricePct }] }" },
          "404": { "description": "Unknown cover analysis, or no linked Nexus Mutual listing." }
        }
      }
    },
    "/api/cover/v1/market/{provider}/{product}/pools": {
      "get": {
        "operationId": "coverMarketPools",
        "summary": "Underwriter concentration history for one product. Free.",
        "description": "How many pools are allowed to underwrite this product (poolsListed), how many actually carry capacity right now (poolsBearing, always <= poolsListed), and the largest pool's share (topPoolPct). Oldest first, up to 400 recorded points. Objective on-chain/API data, not an opinion, so unsigned.",
        "parameters": [
          { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "example": "nexus-mutual" },
          { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": "uniswap-v3" }
        ],
        "responses": {
          "200": { "description": "{ apiVersion, note, provider, product, count, points: [{ t, poolsListed, poolsBearing, topPoolPct }] }" },
          "404": { "description": "Unknown cover analysis, or no linked Nexus Mutual listing." }
        }
      }
    },
    "/api/cover/v1/chain": {
      "get": {
        "operationId": "coverChainHistory",
        "summary": "Nexus Mutual on-chain metrics, one point per day. Free.",
        "description": "Market-wide (not per-product) daily snapshot: covers ever minted (CoverNFT.totalSupply, on-chain read), pool capital, active cover, MCR ratio, NXM supply, daily NXM burn/mint. Objective on-chain data, not an opinion, so unsigned (no attestation field), unlike check and the full analysis. Recorded going forward from 2026-07-20; cover_nft_count is additionally reconstructed back to 2023 from historical mint/burn logs, so other fields are null on older days by design.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "enum": [30, 90, 180, 365, 730, 2000], "default": 2000 },
            "description": "How many days of history to return, oldest first. Rounded UP to the nearest of these fixed values (cache-friendly, keeps the number of distinct backend queries small regardless of what callers pass). Default 2000 covers the full recorded history."
          }
        ],
        "responses": {
          "200": { "description": "{ apiVersion, note, daysRequested, count, points: [{ day, coverNftCount, poolUsd, activeCoverUsd, mcrRatioPct, nxmSupply, stakedNxm, burnNxm, mintNxm }] }" }
        }
      }
    },
    "/api/cover/v1/claims": {
      "get": {
        "operationId": "coverClaims",
        "summary": "Every submitted Nexus Mutual claim, all products. Free.",
        "description": "Payout track record: does this mutual actually pay, not just does it sell cover. Every claim ever submitted, from on-chain events plus the Claims contract's assessment outcome. status: submitted, accepted, denied, draw, unclaimed, paid. Objective on-chain data, not an opinion, so unsigned.",
        "responses": {
          "200": { "description": "{ apiVersion, note, count, claims: [{ claimId, productId, productName, status, payoutAmount, payoutAsset, payoutUsd, requestedAmount, requestedUsd, submittedAt, paidAt }] }" }
        }
      }
    },
    "/api/covered-badge/{wallet}": {
      "get": {
        "operationId": "coveredBadge",
        "summary": "Embeddable 'users covered' badge (SVG). Free.",
        "description": "Live on-chain check whether the wallet holds active, user-protecting cover. Three states: covered (gold), not covered (grey), check failed (neutral, claims nothing). The full wallet address is rendered inside the image, so a badge copied onto someone else's site shows an address that is not theirs. Cached 30 minutes at the edge; expired cover disappears by itself.",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Treasury address (0x…)"
          }
        ],
        "responses": {
          "200": { "description": "image/svg+xml" },
          "404": { "description": "Invalid address (renders an 'invalid address' badge)." },
          "429": { "description": "Rate limited (renders a neutral badge)." }
        }
      }
    }
  },
  "x-quickstart": [
    "1. Discover: GET /api/cover/v1/analyses (free) for provider/product slugs, score, audience, cheapest premium. Every path below uses these slugs.",
    "2. Optional: GET /api/cover/v1/schema (free) to preview the exact response shape before paying.",
    "3. Try it free: /check answers 'does this cover pay for my risk' (coverage gap map + red flags), no payment, no receipt, call it as often as you like.",
    "4. Go deeper (paid): /analyses/{provider}/{product} is the full report, 7 score categories, claims history, capital adequacy (default 4.99 USD, x402). The first call returns HTTP 402 with a PaymentRequirements challenge (see x-payment below and /.well-known/x402.json's payment.example for the exact EIP-712 signing steps), then retry the same GET with an X-PAYMENT header. A receipt then unlocks it again for 7 days.",
    "5. Optional purchase: GET .../buy-quote?amount=&period=&coverAsset=&owner= (free) returns ready-to-sign buyCoverParams for the Nexus CoverBroker contract (0xCB2B736652D2dBf7d72e4dB880Cf6B7d99507814) on Ethereum mainnet, chainId 1 - a DIFFERENT chain from the Base/Polygon x402 payment in step 4 (chainId 8453 / 137). coverAsset decimals: 0=ETH/1=DAI 18, 6=USDC 6, 7=cbBTC 8 - amount must already be in these units when you call buy-quote. Sign and submit the transaction yourself; surface the response's compliance notices to your principal first.",
    "6. Optional: POST { txHash } to /api/cover/buy-confirm (free) once the purchase transaction lands on-chain.",
    "/api/covered-badge/{wallet} is unrelated to this flow: a standalone live on-chain check whether a wallet holds cover, meant for embedding.",
    "/api/cover/v1/chain is also unrelated to this flow: market-wide on-chain metrics of the mutual itself, one point per day, not tied to a single product.",
    "/api/cover/v1/claims is also unrelated to this flow: every submitted claim across all products, with its assessment outcome and payout.",
    "/api/cover/v1/market/{provider}/{product}/history and .../pools are also unrelated to this flow: per-product time series (capacity/premium, underwriter concentration) for charting, not part of the analysis purchase."
  ],
  "x-payment": {
    "protocol": "x402",
    "networks": ["base", "polygon"],
    "asset": "USDC",
    "flow": "HTTP 402 -> pick one accepts[] entry matching a network above -> sign EIP-3009 transferWithAuthorization -> retry with X-PAYMENT header",
    "paid": [
      "/api/cover/v1/analyses/{provider}/{product}"
    ],
    "free": [
      "/api/cover/v1/analyses",
      "/api/cover/v1/analyses/{provider}/{product}/check",
      "/api/cover/v1/schema",
      "/api/cover/v1/analyses/{provider}/{product}/buy-quote",
      "/api/cover/buy-confirm",
      "/api/covered-badge/{wallet}",
      "/api/cover/v1/chain",
      "/api/cover/v1/claims",
      "/api/cover/v1/market/{provider}/{product}/history",
      "/api/cover/v1/market/{provider}/{product}/pools"
    ]
  },
  "x-mcp": {
    "available": true,
    "tools": ["cover_list", "cover_analysis", "cover_check", "cover_buy_quote"],
    "note": "These four tools ship in the dedicated coverraccoon-mcp npm package. The same four tools also still work in the older reputa-mcp package under a reputa_ prefix (reputa_cover_list etc.), kept only for backward compatibility with existing agent configurations."
  }
}