内容
# @tradallo/reputation
[](https://www.npmjs.com/package/@tradallo/reputation)
[](./LICENSE)
[](https://modelcontextprotocol.io)
[](https://smithery.ai/servers/tradallo/reputation)
MCP 服务器 **+ TypeScript 客户端 + 命令行工具**，用于 [Tradallo 验证记录协议](https://tradallo.com)。三种查询加密验证的人类和代理交易记录的方式：
```bash
# 命令行工具 — 漂亮的终端卡片，无需安装
npx @tradallo/reputation card alpha-momentum-v3 --agent
# MCP — 集成到 Claude Desktop / Cursor / 任意 MCP 客户端（配置见下）
# 编程方式 — 类型化的 TS/JS 客户端
import { TradalloClient } from "@tradallo/reputation";
```
每个响应在呈现之前都会 **经过 JCS 规范化 + ed25519 验证**，验证使用 Tradallo 在 `tradallo.com/.well-known/tradallo-pubkeys.json` 中发布的公钥。签名位于信封中；此客户端获取公钥注册表，解析 `key_id`，验证签名，然后返回数据。通过 `served_at` + `max_age_seconds` 实现重放保护。
## 安装
### Claude Desktop
在 `claude_desktop_config.json` 中添加（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"tradallo-reputation": {
"command": "npx",
"args": ["-y", "@tradallo/reputation"]
}
}
}
```
重启 Claude Desktop。Tradallo 工具应出现在工具调色板中。
### Cursor
在 `~/.cursor/mcp.json` 中添加（或通过 Cursor 设置 → MCP）：
```json
{
"mcpServers": {
"tradallo-reputation": {
"command": "npx",
"args": ["-y", "@tradallo/reputation"]
}
}
}
```
### 通用 MCP 客户端
```bash
npx @tradallo/reputation
```
通过 stdio 进行 MCP 通信。
### 本地开发 / 测试环境
通过设置 `TRADALLO_BASE_URL` 指向您自己的部署：
```json
{
"mcpServers": {
"tradallo-reputation": {
"command": "npx",
"args": ["-y", "@tradallo/reputation"],
"env": { "TRADALLO_BASE_URL": "http://localhost:3000" }
}
}
}
```
## 命令行工具
同一个二进制文件在调用子命令时兼作终端命令行工具：
```bash
# 带有验证状态、统计数据、版本元数据的漂亮卡片
npx @tradallo/reputation card alpha-momentum-v3 --agent
# 原始验证 JSON（用于输送到 jq 等）
npx @tradallo/reputation track-record alpha-momentum-v3 --agent
# 发现
npx @tradallo/reputation search --min-sharpe 1.5 --min-trades 200 --sort-by sharpe
# 代理版本历史
npx @tradallo/reputation versions alpha-momentum-v3
# 分页 UTR
npx @tradallo/reputation utrs alpha-momentum-v3 --limit 50
# 查找特定 UTR 的哈希值
npx @tradallo/reputation verify <sha256-hex> alpha-momentum-v3
# 帮助
npx @tradallo/reputation help
```
设置 `NO_COLOR=1` 可禁用 ANSI。设置 `TRADALLO_BASE_URL` 可覆盖 API 基地址。
## 编程客户端
在您自己的 TS/JS 代码中嵌入验证客户端：
```ts
import { TradalloClient } from "@tradallo/reputation";
const client = new TradalloClient(); // 默认 https://tradallo.com
// 如果签名无效、重放窗口过期或公钥未知，则抛出异常。
// 返回已验证的 `data` 有效载荷（不是信封包装器）。
const record = await client.getSigned<{ stats: { all_time: { sharpe_ratio: number | null } } }>(
"/api/v1/agents/alpha-momentum-v3/track-record",
);
if ((record.stats.all_time.sharpe_ratio ?? 0) >= 1.5) {
// ... 委托资本，复制交易等
}
```
验证流程发生在 `getSigned` 内部。如果任何检查失败，工具调用将返回错误而不是数据。代理将被告知原因。
## 工具
### `get_track_record(handle, principal_type?)`
获取 Tradallo 配置文件或代理的验证交易记录。
**输入：**
- `handle`（字符串，必填）— Tradallo 句柄（例如 `aaronjordan`，`alpha-momentum-v3`）
- `principal_type`（`"human"` | `"agent"`，可选，默认 `"agent"`）— 要查找的命名空间
**返回：** 完整的签名有效载荷（验证级别，包括 Sharpe 比率、最大回撤率、胜率、PnL、期望值等的全时和滚动 30/90/365 天统计数据）。
**示例用法：** “显示 Aaron Jordan 在 Tradallo 上的验证交易记录。”
### `search_records(filters)`
发现符合性能标准的验证记录。
**输入（均可选）：** `min_sharpe`、`min_trades`、`max_drawdown`、`venue`、`principal_type`、`sort_by`、`limit`。
**返回：** 按统计数据排序的人类/代理摘要的签名验证列表。
### `verify_utr(utr_hash)`
通过哈希查找通用交易收据。返回 Tradallo 是否通过 Solana 备忘录将该哈希锚定在链上，以及链、签名、插槽、发布时间、Solana 资源管理器 URL 和记账者公钥，以便调用者可以独立验证链上信息。
**返回：** `{ found, anchored_on_chain, chain?, signature?, slot?, posted_at?, explorer_url?, notarizer_pubkey? }`。
### `get_versions(agent_handle)`
获取代理的完整版本历史（语义版本号、版本哈希、策略哈希、每个版本部署和替换的时间）。签名验证。
### `get_utrs(agent_handle, since?, limit?)`
获取代理的原始通用交易收据，按 `closed_at` 分页游标样式。每个收据包括 Tradallo 重新计算的 SHA-256 哈希，以便消费者可以现成检查个别记录。
## 验证工作原理
每个签名的 Tradallo API 响应都将数据封装在具有 ed25519 签名的 JCS 规范化（RFC 8785）信封中：
```json
{
"data": { ... },
"schema_version": "1",
"served_at": "2026-04-30T22:29:52.776Z",
"max_age_seconds": 60,
"signature": {
"alg": "ed25519",
"key_id": "tradallo-prod-2026-04",
"sig": "<base64>"
}
}
```
此 MCP 服务器：
1. 获取 `/.well-known/tradallo-pubkeys.json`（缓存 5 分钟）
2. 解析 `signature.key_id` → ed25519 公钥
3. 对 `{data, schema_version, served_at, max_age_seconds}` 进行 JCS 规范化
4. 使用公钥验证签名
5. 拒绝 `now > served_at + max_age_seconds` 的响应（重放保护）
如果任何检查失败，工具调用将返回错误而不是数据。代理将被告知原因。
## 为什么这很重要
身份（谁是代理）和支付（如何支付）由 x402、MPP、Coinbase Agentic Wallets 和 ERC-8004 在 2026 年解决。**声誉不是。** 当代理决定是否委托资本、复制交易或订阅另一个方的信号时，它需要一种方法来询问：“他们的记录是真实的吗？”
此 MCP 服务器是询问该问题的最低摩擦方式。
## x402 — 即将推出
今天，公共 API 是匿名的，并且受到 IP 速率限制（60 req/min）。我们正在通过 [x402](https://x402.org) 推出分层访问，HTTP 402 支付必填标准，以便代理可以支付 USDC 微交易在 Base 上以绕过速率限制并解锁更高吞吐量的分层，而无需任何注册或 API 密钥操作。
前向兼容的期望：
- 匿名：60 req/min/IP（今日，免费）
- 活跃订阅者：通过 API 密钥 600 req/min（开发中 - 阶段 4.4）
- **x402 微支付**：用于一次性重查询的每调用 USDC 支付；无需帐户（计划阶段 4.5）
- 操作员 / 机队层：Webhook 订阅、自定义子域、优先级索引
一旦促进者管道连通，速率限制响应将获得一个 `x402` 支付选项块。此 MCP 服务器将在看到带有 x402 元数据的 402 时自动支付。在此之前，所有查询都是免费且可验证的。
## 参考代理
一个查询 Tradallo 然后委托资本的工作示例代理：[github.com/tradallo/agent](https://github.com/tradallo/agent)。
## 规格和文档
- 协议概述：[docs/PROTOCOL.md](https://github.com/tradallo/tradallo/blob/main/docs/PROTOCOL.md)
- 规格：[docs/SPEC_V1.1.md](https://github.com/tradallo/tradallo/blob/main/docs/SPEC_V1.1.md)
- 公共 API：https://tradallo.com/api/v1/
- 公钥注册表：https://tradallo.com/.well-known/tradallo-pubkeys.json
## 更新日志
参见 [CHANGELOG.md](./CHANGELOG.md)。
## 许可证
MIT
