> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OTR信任查询REST API参考文档

> OTR信任查询REST API完整技术参考文档，涵盖GET /api/otr/verify端点请求格式与六维度信任评分JSON响应结构详解、免费额度与付费套餐的速率限制规则说明，并提供JavaScript、Python和cURL等多语言集成的完整代码示例与错误处理方案

# REST API 参考

## 6.1 API概述

OTR REST API 供 AI 代理、开发者和平台查询任意域名的信任评分。主站提供匿名查询额度（无需密钥，供轻度使用），生产量请使用 `api.orbexa.io` 版本化 v1 API。

**基础URL**: `https://orbexa.io/api/otr/verify/:domain`

**特点**:

* 匿名额度（主站）: 每 IP 24 小时 5 次查询，无需 API 密钥
* 生产使用走 `api.orbexa.io/v1/*`：Bearer Key 或 x402 付款头（按端点 USDC，Base 链结算）
* 新账号注册获一次性 grant：50 units + \$5 credit，90 天有效
* 订阅套餐：Pro $149/月、Business $499/月、Scale $1,999/月、Enterprise 起 $4,999/月（详见[定价页面](https://orbexa.io/zh/pricing/)）
* 六维度评分，77 项验证信号逐条明细
* 全部数据来源于公开可验证的权威机构
* JSON 标准响应格式

## 6.2 查询端点

### GET /api/otr/verify/:domain

查询指定域名的OTR信任评分。

**请求示例**:

```bash theme={null}
curl https://orbexa.io/api/otr/verify/example.com
```

**路径参数**:

| 参数       | 类型     | 必填 | 说明             |
| -------- | ------ | -- | -------------- |
| `domain` | string | 是  | 要查询的域名（不含协议前缀） |

### 响应结构

响应为JSON格式，包含以下顶层字段：

```json theme={null}
{
  "domain": "example.com",
  "name": "Example Store",
  "trust_score": 75,
  "badge": "SILVER",
  "industry": "E-Commerce",
  "dimensions": {
    "V": { "score": 82, "signals": [...] },
    "S": { "score": 68, "signals": [...] },
    "G": { "score": 70, "signals": [...] },
    "T": { "score": 65, "signals": [...] },
    "D": { "score": 72, "signals": [...] },
    "F": { "score": null, "status": "cold_mode" }
  },
  "entity_data": {
    "gleif": { ... },
    "wikidata": { ... },
    "stock": { ... }
  },
  "agent_commerce": {
    "llms_txt": true,
    "agent_json": false,
    "schema_org_product": true,
    "sitemap": true
  },
  "scanned_at": "2026-04-10T12:00:00Z",
  "otr_id": "OTR-xxxx"
}
```

### 响应字段详解

| 字段               | 类型     | 说明                                  |
| ---------------- | ------ | ----------------------------------- |
| `domain`         | string | 查询的域名                               |
| `name`           | string | 商家名称（品牌名优先）                         |
| `trust_score`    | number | 0-100的综合信任评分                        |
| `badge`          | string | PLATINUM/GOLD/SILVER/BRONZE/UNRATED |
| `industry`       | string | 行业分类                                |
| `dimensions`     | object | 六个维度的分数和信号明细                        |
| `entity_data`    | object | 第三方验证的实体信息                          |
| `agent_commerce` | object | AI代理商务能力声明                          |
| `scanned_at`     | string | 最近一次扫描时间（ISO 8601）                  |
| `otr_id`         | string | OTR唯一标识符                            |

### 维度信号结构

每个维度下的 `signals` 数组包含该维度的所有信号：

```json theme={null}
{
  "signal_name": "dnssec",
  "status": "detected",
  "value": true,
  "evidence": "DNSSEC is enabled with RRSIG records",
  "source_url": "dns://example.com"
}
```

| 字段            | 类型     | 说明                                                   |
| ------------- | ------ | ---------------------------------------------------- |
| `signal_name` | string | 信号标识名                                                |
| `status`      | string | detected / not\_found / not\_scanned / fetch\_failed |
| `value`       | any    | 信号的具体值（布尔/字符串/数字）                                    |
| `evidence`    | string | 证据描述                                                 |
| `source_url`  | string | 数据来源链接（可验证）                                          |

## 6.3 .well-known端点

OTR也提供标准的 `.well-known` 端点，符合Web标准的服务发现规范：

### GET /.well-known/otr/verify/:domain

与主API返回相同的数据结构，但遵循 `.well-known` URI规范（RFC 8615）。

```bash theme={null}
curl https://orbexa.io/.well-known/otr/verify/example.com
```

## 6.4 限速策略

### API查询限速

| 端点    | 限额         | 窗口  |
| ----- | ---------- | --- |
| API端点 | 60次        | 每分钟 |
| 批量查询  | 建议每次调用间隔1秒 |     |

超出限速时API返回HTTP 429，附带`Retry-After`响应头。自动化集成建议实现指数退避重试。

### 扫描提交限制

通过扫描提交表单发起新的OTR扫描请求受以下限制：

| 范围  | 限额   | 窗口       |
| --- | ---- | -------- |
| 按域名 | 3次   | 7天滚动窗口   |
| 按邮箱 | 10次  | 24小时滚动窗口 |
| 全局  | 100次 | 每天       |

* 域名超限提示："This domain has been submitted too many times. Please try again next week."
* 邮箱超限提示："Too many requests from this email. Please try again tomorrow."
* 扫描在2小时内未完成将自动标记为失败。

### 常见扫描错误

| 错误码                   | HTTP | 触发场景            |
| --------------------- | ---- | --------------- |
| `SCAN_IN_PROGRESS`    | 409  | 该域名已有扫描正在进行     |
| `DOMAIN_NOT_FOUND`    | 404  | 域名尚未扫描，需先提交扫描请求 |
| `RATE_LIMIT_EXCEEDED` | 429  | 扫描提交限制已超出       |

## 6.5 集成示例

### JavaScript/Node.js

```javascript theme={null}
async function checkTrust(domain) {
  const response = await fetch(
    `https://orbexa.io/api/otr/verify/${encodeURIComponent(domain)}`
  );
  const data = await response.json();

  console.log(`域名: ${data.domain}`);
  console.log(`信任评分: ${data.trust_score}`);
  console.log(`徽章: ${data.badge}`);
  console.log(`V维度: ${data.dimensions.V.score}`);
  console.log(`S维度: ${data.dimensions.S.score}`);

  return data;
}

// 使用
checkTrust('example.com');
```

### Python

```python theme={null}
import requests

def check_trust(domain: str) -> dict:
    url = f"https://orbexa.io/api/otr/verify/:domain"
    response = requests.get(url)
    data = response.json()

    print(f"域名: {data['domain']}")
    print(f"信任评分: {data['trust_score']}")
    print(f"徽章: {data['badge']}")

    return data

# 使用
check_trust("example.com")
```

### cURL

```bash theme={null}
# 查询并格式化输出
curl -s https://orbexa.io/api/otr/verify/example.com | jq .

# 只获取信任评分
curl -s https://orbexa.io/api/otr/verify/example.com | jq '.trust_score, .badge'
```

## 6.6 用AI代理自动查询

你可以让ChatGPT、Claude等AI助手帮你查询和分析信任评分。示例提示词：

```
请帮我查询 example.com 的OTR信任评分。
访问 https://orbexa.io/api/otr/verify/example.com
然后分析每个维度的分数，告诉我最需要改进的地方，
并给出具体的操作步骤。
```

AI代理会自动调用API、解析结果，并给出个性化的优化建议。这就是"用自己的AI实现"的意思，你不需要安装任何ORBEXA的产品，只需要一个能联网的AI助手。

## 6.7 自建信任评估

如果你想自己搭建类似的信任评估系统（例如只评估自己的供应链），OTR协议的核心逻辑是开源的：

* **OTR协议规范**: [github.com/yb48666-ctrl/OTR-Protocol-by-orbexa](https://github.com/yb48666-ctrl/OTR-Protocol-by-orbexa)
* **评估的数据源都是公开的**: GLEIF、Wikidata、Finnhub、SEC EDGAR、DNS记录、SSL证书等
* **你可以按照自己的需求调整权重和信号**

ORBEXA提供的是一个现成的实现，但协议本身是开放的，任何人都可以基于同样的原理构建自己的信任评估。

***

**下一章**: [MCP Server — 信任查询工具](/zh/book-2/ch7-mcp-server) — 通过MCP协议让AI代理直接调用OTR信任查询