{
 "openapi": "3.1.0",
 "info": {
  "title": "CVIN — 算力资产登记与解析协议",
  "version": "1.0.0",
  "summary": "给每一颗 GPU 一个跨运营方、全球唯一、机器可验证的身份。登记与观测只做事实记录，不出信用评分。",
  "description": "## 这是什么\nCVIN 是一套 GPU 资产登记协议：设备用「型号前缀 + 序列号哈希」得到一个稳定编码（CVIN），\n围绕这个编码累积观测记录（挂牌、成交、遥测、签名证明、抵押登记），形成可独立复算的哈希链。\n\n## 三条必须先读的口径\n1. **身份分级**：M（型号级报价）/ L0（挂牌指纹）/ L1（序列号哈希）/ L2（硬件信任根）。\n   只有 L2 可跨运营方核验。当前真实采集的设备全部为 L0，`usable_for` 不含抵押登记。\n2. **价格不是成交价**：返回的是公开挂牌价快照，不是成交价；极值不裁剪，P10/P90 只作分布参考。\n3. **不要相加**：设备级机器数（/v1/market/models）与型号级报价（rentgpu.link / RunPod）口径不同，相加即错。\n\n## 免费与付费\n`/v1/resolve`、`/v1/market/models`、`/v1/identity`、`/v1/provenance`、`/v1/stats`、`/v1/levels` 永久免费、无需鉴权。\n`/v1/history`、`/v1/verify`、`/v1/liens`、`/v1/report` 需订阅 key（头 `x-api-key` 或 `Authorization: Bearer`）或按次 x402 付费。\n写入端（`/v1/declare`、`/v1/attest`）永远免费。\n\n## 一个重要约定\n查询的设备若不在登记表中，`encumbrance.has_active_lien` 返回 **null 而不是 false**。\nnull 表示「不知道」，不是「没有」。请勿把 null 当 false 放行。\n\n## 其他入口\n- MCP：`POST /mcp`（JSON-RPC 2.0，工具 cvin_resolve / cvin_history / cvin_verify / cvin_market_models 等）\n- 数据授权：`/LICENSE-DATA`（注意：账本为混装文件，第三方来源不随 CC0 释出）\n- 变更与合规边界：/llms.txt、/provenance",
  "contact": {
   "name": "CVIN",
   "url": "https://cvin.org/contact"
  },
  "license": {
   "name": "Apache-2.0 (代码) / CC0-1.0 (自有数据) / CC-BY-4.0 (规范)",
   "url": "https://cvin.org/LICENSE"
  }
 },
 "servers": [
  {
   "url": "https://cvin.org",
   "description": "生产环境"
  }
 ],
 "tags": [
  {
   "name": "free",
   "description": "永久免费、无需鉴权"
  },
  {
   "name": "paid",
   "description": "订阅 key 或 x402 按次付费"
  },
  {
   "name": "write",
   "description": "写入端点：永远免费，但有频率限制"
  },
  {
   "name": "market",
   "description": "行情数据"
  }
 ],
 "paths": {
  "/v1/resolve/{cvin}": {
   "get": {
    "summary": "解析一个 CVIN（永久免费、无限次）",
    "tags": [
     "free"
    ],
    "operationId": "resolveCvin",
    "description": "返回设备是否存在、身份分级、观测计数、最近观测时间与**抵押权风险信号**。\n\n免费层只给 90 天窗口内的观测**条数**，逐条明细属付费层。\n\n⚠️ 设备不存在时 `exists:false` 且 `encumbrance.known:false`，风险字段一律 `null`——表示未知，不是无风险。",
    "parameters": [
     {
      "name": "cvin",
      "in": "path",
      "required": true,
      "description": "规范的 CVIN 编码。格式 cvin:<mfr>.<model>.<form>.<mem>:<serial-hash-16>。路径里出现冒号时请 URL 编码为 %3A。",
      "schema": {
       "type": "string",
       "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$",
       "example": "cvin:nv.h100.sxm.80g:3ij511ie1hb8e1r6"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "解析结果（按设备状态分三态：已登记 / 未登记 / 格式错误）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ResolveResult"
        },
        "examples": {
         "已登记": {
          "value": {
           "tier": "free",
           "cvin": "cvin:nv.rtx5090.pcie.32g:yytqqif2pv2anyhb",
           "exists": true,
           "scope": "device",
           "is_device": true,
           "status": "active",
           "identity": {
            "level": "L0",
            "cross_operator": false,
            "usable_for": [
             "市场行情"
            ],
            "not_usable_for": [
             "抵押登记",
             "保险核保"
            ]
           },
           "encumbrance": {
            "known": true,
            "has_active_lien": false,
            "active_liens": 0,
            "duplicate_pledge_risk": false
           }
          }
         },
         "未登记": {
          "value": {
           "tier": "free",
           "cvin": "cvin:nv.rtx4090.pcie.24g:zzzzzzzzzzzzzzzz",
           "exists": false,
           "encumbrance": {
            "known": false,
            "has_active_lien": null,
            "active_liens": null,
            "duplicate_pledge_risk": null,
            "note": "该 CVIN 尚未出现在登记表中，抵押权状态「未知」——不是「无抵押权」。null ≠ false，不得据此放行。"
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "CVIN 格式不合法（invalid_cvin / missing_argument）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/market/models": {
   "get": {
    "summary": "型号级行情快照（永久免费）",
    "tags": [
     "market"
    ],
    "operationId": "marketModels",
    "description": "按型号聚合的**设备级真实挂牌**行情：去重机器数 + 单卡小时价 P10 / 中位 / P90 + 平台 + 地区 + 快照时间。\n\n三种折算已做完：整机价÷卡数、整天价÷24、同一台机器重复挂牌按 CVIN 去重。\n\n口径写在 `caliber` 块里；`data_quality` 给出记录级合成占比；`attribution` 列出本端点内各平台的许可状态。**型号级报价（rentgpu.link / RunPod）不在本端点内，不得与这里的机器数相加。**",
    "responses": {
     "200": {
      "description": "型号级行情快照",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/MarketModels"
        },
        "example": {
         "as_of": "2026-11-05T07:45:00.000Z",
         "scope": "device_level_listing",
         "identity_grade": "L0",
         "totals": {
          "models": 150,
          "machines": 4867,
          "records": 8441,
          "median_usd_h": 0.2542
         },
         "models": [
          {
           "model": "nv.rtx5090",
           "name": "NVIDIA RTX 5090",
           "page": "/model/nv.rtx5090",
           "machines": 463,
           "records": 612,
           "per_gpu_usd_h": {
            "p10": 0.31,
            "median": 0.42,
            "p90": 0.78
           },
           "platforms": [
            "vast.ai",
            "clore.ai"
           ],
           "last_seen": "2026-11-05T07:40:11.000Z"
          }
         ],
         "data_quality": {
          "observations": 8441,
          "synthetic": 442,
          "real": 7999,
          "synthetic_share_pct": 5.24
         },
         "caliber": {
          "price_unit": "USD/GPU/hour",
          "not_additive": "型号级报价不在此端点内，也不得与这里的机器数或价格相加"
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/identity/{cvin}": {
   "get": {
    "summary": "设备身份分级与「能断言什么 / 不能断言什么」",
    "tags": [
     "free"
    ],
    "operationId": "identity",
    "description": "返回身份等级（M/L0/L1/L2）、跨运营方核验能力、`usable_for` 与 `not_usable_for` 白名单。做风控前应先读 `not_usable_for`，而不是先看有没有历史。",
    "parameters": [
     {
      "name": "cvin",
      "in": "path",
      "required": true,
      "description": "规范的 CVIN 编码。格式 cvin:<mfr>.<model>.<form>.<mem>:<serial-hash-16>。路径里出现冒号时请 URL 编码为 %3A。",
      "schema": {
       "type": "string",
       "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$",
       "example": "cvin:nv.h100.sxm.80g:3ij511ie1hb8e1r6"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "身份信息",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "CVIN 格式不合法",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/history/{cvin}": {
   "get": {
    "summary": "完整观测时间线",
    "tags": [
     "paid"
    ],
    "operationId": "history",
    "description": "逐条观测记录（含哈希链前后指针）。每个 IP 每天首次调用免费，其后需订阅 key 或 x402 按次付费。",
    "parameters": [
     {
      "name": "cvin",
      "in": "path",
      "required": true,
      "description": "规范的 CVIN 编码。格式 cvin:<mfr>.<model>.<form>.<mem>:<serial-hash-16>。路径里出现冒号时请 URL 编码为 %3A。",
      "schema": {
       "type": "string",
       "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$",
       "example": "cvin:nv.h100.sxm.80g:3ij511ie1hb8e1r6"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "观测列表",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "402": {
      "description": "需要付费。响应体与 PAYMENT-REQUIRED 头里带 x402 挑战；按挑战完成 EIP-3009 授权后，带 X-PAYMENT 头重试同一 URL。",
      "headers": {
       "PAYMENT-REQUIRED": {
        "description": "agent402-service-manifest/1 描述的支付要求（base64 JSON）",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaymentRequired"
        }
       }
      }
     },
     "404": {
      "description": "该 CVIN 无观测记录",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/verify/{cvin}": {
   "get": {
    "summary": "哈希链连续性校验",
    "tags": [
     "paid"
    ],
    "operationId": "verify",
    "description": "逐条复算 prev_hash / hash，判定链是否断裂、是否有记录被替换。每个 IP 每天首次调用免费。",
    "parameters": [
     {
      "name": "cvin",
      "in": "path",
      "required": true,
      "description": "规范的 CVIN 编码。格式 cvin:<mfr>.<model>.<form>.<mem>:<serial-hash-16>。路径里出现冒号时请 URL 编码为 %3A。",
      "schema": {
       "type": "string",
       "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$",
       "example": "cvin:nv.h100.sxm.80g:3ij511ie1hb8e1r6"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "校验结果",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VerifyResult"
        }
       }
      }
     },
     "402": {
      "description": "需要付费。响应体与 PAYMENT-REQUIRED 头里带 x402 挑战；按挑战完成 EIP-3009 授权后，带 X-PAYMENT 头重试同一 URL。",
      "headers": {
       "PAYMENT-REQUIRED": {
        "description": "agent402-service-manifest/1 描述的支付要求（base64 JSON）",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaymentRequired"
        }
       }
      }
     }
    }
   }
  },
  "/v1/liens/{cvin}": {
   "get": {
    "summary": "抵押权登记明细",
    "tags": [
     "paid"
    ],
    "operationId": "liens",
    "description": "出借方名单、金额、合同编号。属风控订阅档。免费层只给计数与风险信号（见 /v1/resolve 的 encumbrance）。",
    "parameters": [
     {
      "name": "cvin",
      "in": "path",
      "required": true,
      "description": "规范的 CVIN 编码。格式 cvin:<mfr>.<model>.<form>.<mem>:<serial-hash-16>。路径里出现冒号时请 URL 编码为 %3A。",
      "schema": {
       "type": "string",
       "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$",
       "example": "cvin:nv.h100.sxm.80g:3ij511ie1hb8e1r6"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "抵押登记列表",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "402": {
      "description": "需要付费。响应体与 PAYMENT-REQUIRED 头里带 x402 挑战；按挑战完成 EIP-3009 授权后，带 X-PAYMENT 头重试同一 URL。",
      "headers": {
       "PAYMENT-REQUIRED": {
        "description": "agent402-service-manifest/1 描述的支付要求（base64 JSON）",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaymentRequired"
        }
       }
      }
     }
    }
   }
  },
  "/v1/report/{cvin}": {
   "get": {
    "summary": "单台核验报告（$2/份）",
    "tags": [
     "paid"
    ],
    "operationId": "report",
    "description": "带编号、签名、内容哈希的可留档报告。**这是只读资源，用 GET**（POST 返回 405）。\n\n零真实观测的设备走 `honest_downgrade`：报告免费签发并显著标注 `demo_report`，内容不构成对该设备真实状态的陈述。",
    "parameters": [
     {
      "name": "cvin",
      "in": "path",
      "required": true,
      "description": "规范的 CVIN 编码。格式 cvin:<mfr>.<model>.<form>.<mem>:<serial-hash-16>。路径里出现冒号时请 URL 编码为 %3A。",
      "schema": {
       "type": "string",
       "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$",
       "example": "cvin:nv.h100.sxm.80g:3ij511ie1hb8e1r6"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "报告已签发（HTTP 200，不是 201——GET 不创建资源）",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "402": {
      "description": "需要付费。响应体与 PAYMENT-REQUIRED 头里带 x402 挑战；按挑战完成 EIP-3009 授权后，带 X-PAYMENT 头重试同一 URL。",
      "headers": {
       "PAYMENT-REQUIRED": {
        "description": "agent402-service-manifest/1 描述的支付要求（base64 JSON）",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaymentRequired"
        }
       }
      }
     },
     "404": {
      "description": "该 CVIN 尚无观测记录，无法出具报告",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/report/verify": {
   "post": {
    "summary": "独立验签（免费）",
    "tags": [
     "free"
    ],
    "operationId": "verifyReport",
    "description": "把 GET /v1/report/{cvin} 返回的 JSON 原样回传，用其中的 `signer_public_pem` 独立验签。不依赖本服务在线即可验证。",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "签名与内容哈希均有效"
     },
     "409": {
      "description": "签名或内容哈希不匹配",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/declare": {
   "post": {
    "summary": "自助登记（免费）",
    "tags": [
     "write"
    ],
    "operationId": "declare",
    "description": "给设备建第一条记录。写入永久免费，限 12 次/小时/IP。序列号在浏览器内哈希，明文不出本机。\n\n注意：声明公开零鉴权且 append-only，任何人都能给任何 CVIN 挂名，冲突会以 `operator_conflict_count` 输出，登记表不做裁决。",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/DeclareRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "已入链"
     },
     "400": {
      "description": "参数非法",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "超过频率限制",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/attest": {
   "post": {
    "summary": "签名遥测上报（免费，需验签）",
    "tags": [
     "write"
    ],
    "operationId": "attest",
    "description": "设备侧用私钥对遥测签名后上报，验签通过才落库。同一设备此前绑定过另一把密钥时返回 409（防密钥替换）。",
    "responses": {
     "201": {
      "description": "已验签并入链"
     },
     "400": {
      "description": "验签失败或遥测为空",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "409": {
      "description": "设备密钥不匹配",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/stats": {
   "get": {
    "summary": "登记表统计",
    "tags": [
     "free"
    ],
    "operationId": "stats",
    "responses": {
     "200": {
      "description": "总量、设备数、合成占比等",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  },
  "/v1/provenance": {
   "get": {
    "summary": "数据出处与合成占比",
    "tags": [
     "free"
    ],
    "operationId": "provenance",
    "description": "按来源列出观测数与性质、第三方署名要求。引用数据前应先读这个。",
    "responses": {
     "200": {
      "description": "出处明细",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  },
  "/v1/levels": {
   "get": {
    "summary": "身份分级定义",
    "tags": [
     "free"
    ],
    "operationId": "levels",
    "responses": {
     "200": {
      "description": "M / L0 / L1 / L2 的定义与可断言范围",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  },
  "/v1/health": {
   "get": {
    "summary": "健康检查",
    "tags": [
     "free"
    ],
    "operationId": "health",
    "responses": {
     "200": {
      "description": "服务与账本可用性"
     }
    }
   }
  },
  "/mcp": {
   "post": {
    "summary": "MCP 端点（JSON-RPC 2.0）",
    "tags": [
     "free"
    ],
    "operationId": "mcp",
    "description": "Model Context Protocol 入口，支持 initialize / tools/list / tools/call。工具包括 cvin_resolve、cvin_history、cvin_verify、cvin_market_models、cvin_encode 等。",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "jsonrpc": {
          "const": "2.0"
         },
         "id": {},
         "method": {
          "type": "string"
         },
         "params": {
          "type": "object"
         }
        },
        "required": [
         "jsonrpc",
         "method"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "JSON-RPC 响应",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "x-api-key",
    "description": "订阅 key。也可用 Authorization: Bearer <key>。"
   },
   "X402Payment": {
    "type": "apiKey",
    "in": "header",
    "name": "X-PAYMENT",
    "description": "x402 按次付费回执。先请求目标 URL 拿到 402 挑战，完成 EIP-3009 授权后带此头重试。"
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string",
      "description": "机器可读的错误码",
      "examples": [
       "invalid_cvin",
       "missing_argument",
       "not_found",
       "method_not_allowed",
       "payment_required"
      ]
     },
     "detail": {
      "type": "string",
      "description": "人可读说明"
     },
     "correct": {
      "type": "string",
      "description": "正确的调用形式（有则给出）"
     },
     "example": {
      "type": "string",
      "description": "可直接照抄的示例 URL"
     }
    },
    "required": [
     "error"
    ]
   },
   "PaymentRequired": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string",
      "const": "payment_required"
     },
     "x402Version": {
      "type": "integer",
      "const": 2
     },
     "accepts": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      },
      "description": "可接受的支付方式（network / asset / payTo / maxAmountRequired）"
     },
     "price_usd": {
      "type": "number"
     },
     "how": {
      "type": "string",
      "description": "怎么完成支付（人读）"
     }
    }
   },
   "Identity": {
    "type": "object",
    "properties": {
     "level": {
      "type": "string",
      "enum": [
       "M",
       "L0",
       "L1",
       "L2"
      ],
      "description": "M=型号级报价（不指向具体设备）；L0=挂牌指纹；L1=序列号哈希；L2=硬件信任根"
     },
     "scope": {
      "type": "string",
      "enum": [
       "model",
       "device"
      ]
     },
     "is_device": {
      "type": "boolean",
      "description": "是否指向一台具体设备。M 级恒为 false。"
     },
     "cross_operator": {
      "type": "boolean",
      "description": "能否跨运营方核验是同一台设备。只有 L2 为 true。"
     },
     "can_assert": {
      "type": "string",
      "description": "这个等级能断言什么"
     },
     "cannot_assert": {
      "type": "string",
      "description": "这个等级不能断言什么"
     },
     "usable_for": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "not_usable_for": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "明确不可以拿它做什么。做风控前先读这一项。"
     }
    }
   },
   "Encumbrance": {
    "type": "object",
    "description": "抵押权状态。known:false 时所有风险字段为 null——null 表示未知，不得当作「无风险」。",
    "properties": {
     "known": {
      "type": "boolean",
      "description": "false = 该设备不在登记表中，抵押权状态未知"
     },
     "has_active_lien": {
      "type": [
       "boolean",
       "null"
      ]
     },
     "active_liens": {
      "type": [
       "integer",
       "null"
      ]
     },
     "duplicate_pledge_risk": {
      "type": [
       "boolean",
       "null"
      ]
     },
     "note": {
      "type": "string"
     }
    },
    "required": [
     "known"
    ]
   },
   "ResolveResult": {
    "type": "object",
    "properties": {
     "tier": {
      "type": "string"
     },
     "cvin": {
      "type": "string"
     },
     "exists": {
      "type": "boolean"
     },
     "scope": {
      "type": "string"
     },
     "is_device": {
      "type": "boolean"
     },
     "status": {
      "type": "string",
      "enum": [
       "active",
       "stale",
       "dormant",
       "unknown"
      ]
     },
     "days_since_last_observation": {
      "type": [
       "integer",
       "null"
      ]
     },
     "attestation_count": {
      "type": "integer"
     },
     "delayed_summary": {
      "type": [
       "object",
       "null"
      ],
      "description": "免费层摘要。observation_count=总条数；delayed_observations=**90 天窗口之外**的条数（不是「被延迟的条数」）；两者之差才是窗口内条数。",
      "properties": {
       "observation_count": {
        "type": "integer"
       },
       "delayed_window_days": {
        "type": "integer"
       },
       "delayed_observations": {
        "type": "integer",
        "description": "窗口外（更早）的观测条数"
       }
      }
     },
     "identity": {
      "$ref": "#/components/schemas/Identity"
     },
     "encumbrance": {
      "$ref": "#/components/schemas/Encumbrance"
     }
    },
    "required": [
     "cvin",
     "exists",
     "encumbrance"
    ]
   },
   "VerifyResult": {
    "type": "object",
    "properties": {
     "cvin": {
      "type": "string"
     },
     "ok": {
      "type": "boolean",
      "description": "哈希链是否完整"
     },
     "checked": {
      "type": "integer",
      "description": "复算了几条记录"
     },
     "broken_at_seq": {
      "type": [
       "integer",
       "null"
      ],
      "description": "链断裂处的序号；null 表示未断"
     }
    }
   },
   "MarketModels": {
    "type": "object",
    "properties": {
     "as_of": {
      "type": "string",
      "format": "date-time"
     },
     "scope": {
      "type": "string"
     },
     "identity_grade": {
      "type": "string",
      "description": "本端点内机器数据的身份等级（恒为 L0）"
     },
     "totals": {
      "type": "object",
      "properties": {
       "models": {
        "type": "integer"
       },
       "machines": {
        "type": "integer"
       },
       "records": {
        "type": "integer"
       },
       "median_usd_h": {
        "type": "number"
       }
      }
     },
     "models": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "model": {
         "type": "string"
        },
        "name": {
         "type": "string"
        },
        "page": {
         "type": "string"
        },
        "machines": {
         "type": "integer",
         "description": "去重后的机器数（不是记录数）"
        },
        "records": {
         "type": "integer"
        },
        "per_gpu_usd_h": {
         "type": "object",
         "properties": {
          "p10": {
           "type": [
            "number",
            "null"
           ]
          },
          "median": {
           "type": [
            "number",
            "null"
           ]
          },
          "p90": {
           "type": [
            "number",
            "null"
           ]
          }
         }
        },
        "platforms": {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        "last_seen": {
         "type": "string",
         "format": "date-time"
        }
       }
      }
     },
     "data_quality": {
      "type": "object",
      "additionalProperties": true
     },
     "caliber": {
      "type": "object",
      "additionalProperties": true,
      "description": "口径定义：价格单位、计价基准、极值处理、不可相加说明"
     },
     "attribution": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     }
    }
   },
   "DeclareRequest": {
    "type": "object",
    "required": [
     "cvin"
    ],
    "properties": {
     "cvin": {
      "type": "string",
      "pattern": "^cvin:[a-z0-9]+(\\.[a-z0-9]+)*:[a-z0-9]{16}$"
     },
     "operator": {
      "type": "string",
      "description": "声明方名称（公开可见，append-only）"
     },
     "attrs": {
      "type": "object",
      "additionalProperties": true,
      "description": "附加属性，如 region / cluster_size / asking_price_usd_h"
     }
    }
   }
  }
 }
}