# SURF 合成数据市场 · 完整接口文档（面向 AI / LLM）

站点：https://surf.3qyyds.top
MCP 端点：https://surf.3qyyds.top/mcp
所有公开 API 返回 JSON，无需鉴权（下单流程亦无需鉴权，支付在链上完成）。

## 数据纯度声明（重要）

- **100% 合成，零真人痕迹**：对外供给一律为 synthetic。所有数据由数字分身在生态圈内生成，不含任何真人身份信息或个人数据（PII）。
- **真人不得入场**：即便是真实用户，也必须先创建数字分身，由分身产生数据；系统中不留真人痕迹。
- **合规优势**：无个人信息主体、无授权链条、无跨境传输问题，规避 GDPR / PIPL 负担。
- **可溯源但不可识别到人**：溯源到的是分身 ID、生产批次与生成器钢印，不可反推真实自然人。
- 内部字段 `sourceType=real` 仅为系统自测残留的隔离标记，**不对外供给、不出现在 MCP 目录与报价中**。

典型用途：模型训练 / 微调 / 冷启动、AI Agent 行为建模与评测、站点 QA 回归语料、GEO 可见度测量基线。

---

## 一、数据模型

每条资产记录（表 pm_task_runs）字段：

| 字段 | 含义 |
|---|---|
| taskId | 语义幂等 ID，格式 `SIM-{TYPE}-{YYYYMMDD}-{hash前10}` |
| taskType | 任务类型：browse / comment / discuss / bazi / name / phone / mbti / game_score / derive |
| siteId | 来源站点：video / jingguan / mo / game |
| sourceType | 对外恒为 synthetic（纯合成）；real 为内部隔离标记，不对外供给 |
| seedRef | 批次号，用于溯源到具体生产批次 |
| generator | 生成器钢印，如 seed-agents-v1 / derive-assets-v1 |
| inputHash | 输入内容哈希 |
| outputHash | 产出内容哈希（写入哈希链的叶子） |
| outputDataJson | 原始产出（打包下载时提供） |
| avatarSig | 分身 ed25519 签名 |
| createdAt | 毫秒时间戳 |

链路：outputHash → pm_chain_links（分身哈希链，含 seq / selfHash / payloadHash）→ 每日 pm_anchor_daily（Merkle Root + RFC3161 TSA + Bitcoin OTS）。

---

## 二、REST 端点

### 1. 资产总览
```
GET /points/assets/stats
```
返回 unitPriceUsd、totals{taskRuns, chainLinks, bytes, estValueUsd, realRuns, syntheticRuns}、bySource[]、latestAnchor{date, merkleRoot, leafCount, chainName, tsa, ots}、categories[]。

### 2. 数据目录（可售清单）
```
GET /points/assets/catalog
```
返回 totalUsd 与 items[]：taskType、siteId、sourceType、records、bytes、withData、signed、unitUsd、estValueUsd。

### 3. 每日锚定
```
GET /points/assets/anchor
```
返回最新锚定的 Merkle Root、TSA/OTS 状态与多链列表（btc-ots、rfc3161 为在线零成本链；其余标记 pending 待激活）。

### 4. 资产证书
```
GET /points/assets/certificate?from=20260901&to=20260908&taskType=browse
```
返回区间内各类型条数、每日 Merkle Root 列表、ed25519 签名 issuerSig、验签公钥 issuerPublicKey、verifyUrl。

### 5. 单条验真
```
GET /points/assets/proof?taskId=SIM-BROWSE-20260908-xxxxxxxxxx
GET /points/assets/proof?hash=<outputHash>&date=20260908
```
返回该记录在哈希链中的 seq、selfHash，以及用当日叶子集复核 Merkle Root 所需信息。

### 6. 打包（生成可购买数据包）
```
POST /points/assets/package
Content-Type: application/json

{ "taskType": "browse", "siteId": "video", "sourceType": "real",
  "from": "2026-09-01", "to": "2026-09-08", "limit": 500 }
```
返回 packageId、rows、unitUsd、totalUsd。游客每 10 分钟限 10 次，单次上限 1000 条。

### 7. 下单
```
POST /points/assets/order
Content-Type: application/json

{ "packageId": "PKG-xxxx", "buyer": "your-org", "contact": "you@example.com" }
```
返回 orderNo、totalUsd、expectedAmount（唯一待付金额，含 dust 尾数用于自动对账）、pay{chain, token, wallet, contract}。

### 8. 查询订单
```
GET /points/assets/order?orderNo=ORD-20260908-XXXXXXXX
```
status 为 paid 时返回 downloadToken 与 downloadUrl。

---

## 三、MCP Server

端点：`POST https://surf.3qyyds.top/mcp`
协议：MCP Streamable HTTP（JSON-RPC 2.0），支持单请求与 batch，响应 `application/json`。
`GET /mcp` 返回服务说明与工具清单。

### 握手
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
```
```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"surf-data-assets","version":"1.0.0"}}}
```

### 列工具
```json
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
```

### 调工具
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"surf_search_catalog","arguments":{"taskType":"browse"}}}
```
返回 `result.content[0].text`（文本化结果）与 `result.structuredContent`（结构化结果）。

### 工具清单

| 工具 | 说明 | 主要入参 |
|---|---|---|
| surf_asset_stats | 资产总览与最新锚定 | — |
| surf_search_catalog | 检索可售目录 | taskType, siteId, sourceType, minRecords |
| surf_get_quote | 按条数报价 | taskType, siteId, records |
| surf_create_package | 打包数据集 | taskType, siteId, sourceType, from, to, limit |
| surf_create_order | 创建订单（USDT TRC-20） | packageId, buyer, contact |
| surf_get_order | 查支付状态与下载令牌 | orderNo |
| surf_verify_proof | 单条上链验真 | taskId 或 hash, date |
| surf_get_certificate | 区间资产证书 | from, to, taskType |
| surf_latest_anchor | 最新每日锚定 | — |

### curl 示例
```bash
curl -sS https://surf.3qyyds.top/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"surf_asset_stats","arguments":{}}}'
```

---

## 四、Agent 发现

- A2A Agent Card：`GET /.well-known/agent.json`
- MCP 客户端配置：`GET /.well-known/mcp.json`
- Agentic Commerce 能力声明（ERC-8183 / x402 / Agent Data Exchange）：`GET /.well-known/agent-commerce.json`

## 五、合规

盲测与种子行为仅用于数据生产与测量，严禁信源造假、刷量与排名操纵。合成数据一律标注 sourceType=synthetic 与 generator 钢印，不得以真人数据名义出售。