reputation

@tradallo/reputation

适用于 Tradallo Verified Record Protocol 的 MCP 服务 + TypeScript 客户端 + CLI。提供三种方式查询经过加密验证的人类和 Agent 交易记录：

# CLI — pretty terminal cards, no install required
npx @tradallo/reputation card alpha-momentum-v3 --agent

# MCP — drop into Claude Desktop / Cursor / any MCP client (config below)

# Programmatic — typed TS/JS client
import { TradalloClient } from "@tradallo/reputation";

每个响应都会先依据 Tradallo 发布在 tradallo.com/.well-known/tradallo-pubkeys.json 的公钥，进行 JCS 规范化 + ed25519 验证，然后才会提供给调用方。签名保存在信封中；此客户端会获取公钥注册表，解析 key_id，验证签名，之后才返回数据。通过 served_at + max_age_seconds 防止重放。

安装

Claude Desktop

将配置添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "tradallo-reputation": {
      "command": "npx",
      "args": ["-y", "@tradallo/reputation"]
    }
  }
}

重启 Claude Desktop。Tradallo 工具应会出现在工具面板中。

Cursor

将配置添加到 ~/.cursor/mcp.json（或通过 Cursor Settings → MCP 添加）：

{
  "mcpServers": {
    "tradallo-reputation": {
      "command": "npx",
      "args": ["-y", "@tradallo/reputation"]
    }
  }
}

通用 MCP 客户端

npx @tradallo/reputation

通过 stdio 使用 MCP 通信。

本地开发 / 暂存环境

设置 TRADALLO_BASE_URL，指向你自己的部署：

{
  "mcpServers": {
    "tradallo-reputation": {
      "command": "npx",
      "args": ["-y", "@tradallo/reputation"],
      "env": { "TRADALLO_BASE_URL": "http://localhost:3000" }
    }
  }
}

CLI

使用子命令调用时，同一个二进制文件也可作为终端 CLI 使用：

# Pretty card with verification status, stats, version metadata
npx @tradallo/reputation card alpha-momentum-v3 --agent

# Raw verified JSON (for piping into jq, etc.)
npx @tradallo/reputation track-record alpha-momentum-v3 --agent

# Discovery
npx @tradallo/reputation search --min-sharpe 1.5 --min-trades 200 --sort-by sharpe

# Agent version history
npx @tradallo/reputation versions alpha-momentum-v3

# Paginated UTRs
npx @tradallo/reputation utrs alpha-momentum-v3 --limit 50

# Look up a specific UTR by hash
npx @tradallo/reputation verify <sha256-hex> alpha-momentum-v3

# Help
npx @tradallo/reputation help

NO_COLOR=1 可禁用 ANSI 颜色。TRADALLO_BASE_URL 可覆盖 API 基础 URL。

程序化客户端

将验证客户端嵌入你自己的 TS/JS 代码：

import { TradalloClient } from "@tradallo/reputation";

const client = new TradalloClient(); // defaults to https://tradallo.com

// Throws if signature invalid, replay window expired, or pubkey unknown.
// Returns the verified `data` payload (not the envelope wrapper).
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) {
  // ... delegate capital, copy trades, etc.
}

验证流程在 getSigned 内部执行。如果出现任何问题——签名无效、信封过期、密钥未知或架构不匹配——调用都会抛出异常。你永远不会看到未经验证的数据。

工具

get_track_record(handle, principal_type?)

获取 Tradallo 个人资料或 Agent 的已验证交易记录。

输入：

• handle（string，必填）——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。

**返回：**按排序的个人和 Agent 摘要列表及其统计数据。签名已验证。

verify_utr(utr_hash)

按哈希查找 Universal Trade Receipt。返回 Tradallo 是否已通过 Solana memo 将该哈希锚定到链上；如果已锚定，还会返回链、签名、slot、posted_at、Solana Explorer URL 和公证者公钥，方便调用方独立验证链上记录。

返回：{ found, anchored_on_chain, chain?, signature?, slot?, posted_at?, explorer_url?, notarizer_pubkey? }。

get_versions(agent_handle)

获取 Agent 的完整版本历史（semver 标签、version_hash、policy_hash，以及每个版本的部署和被替代时间）。签名已验证。

get_utrs(agent_handle, since?, limit?)

获取 Agent 的原始 Universal Trade Receipt，按 closed_at 使用游标方式分页。每条回执都包含 Tradallo 重新计算的 SHA-256 哈希，方便使用方抽查单条记录。

验证机制

每个经过签名的 Tradallo API 响应都会将数据封装在一个经过 JCS 规范化（RFC 8785）的信封中，并附带 ed25519 签名：

{
  "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 的响应（防止重放攻击）

如果任何一项检查失败，工具调用将返回错误，而非数据，并告知 Agent 原因。

这为何重要

身份（Agent 是谁）和支付（如何付款）已于 2026 年通过 x402、MPP、Coinbase Agentic Wallets 和 ERC-8004 解决。信誉问题尚未解决。 当 Agent 决定是否将资金委托给另一方、复制其交易或订阅其信号时，需要一种方法来询问：“对方的交易记录是真的吗？”

此 MCP 服务是提出这个问题的最简单方式。

x402 — 即将推出的功能

目前，公共 API 无需身份验证，并按 IP 限流（60 次请求/分钟）。我们正在通过 x402 推出分级访问，这是一种 HTTP 402 付费要求标准，Agent 可在 Base 上使用 USDC 进行小额交易，以绕过速率限制并解锁更高吞吐量的级别，无需注册或配置 API 密钥。

向后兼容的预期功能：

• 匿名用户：60 次请求/分钟/IP（当前免费）
• 活跃订阅用户：通过 API 密钥实现 600 次请求/分钟（开发中 — Phase 4.4）
• x402 小额支付：针对单次高负载查询按次支付 USDC；无需账户（计划于 Phase 4.5 推出）
• 运营方 / Fleet 级别：Webhook 订阅、自定义子域名、优先索引

接入支付处理流程后，速率限制响应将新增一个 x402 支付选项区块。此 MCP 服务在检测到包含 x402 元数据的 402 响应时，将开始自动付款。在此之前，所有查询均免费且可验证。

参考 Agent

一个在委托资金前查询 Tradallo 的可用 Agent 示例： github.com/tradallo/agent。

规范与文档

• 协议概述：docs/PROTOCOL.md
• 规范：docs/SPEC_V1.1.md
• 公共 API：https://tradallo.com/api/v1/
• 公钥注册表：https://tradallo.com/.well-known/tradallo-pubkeys.json

更新日志

参见 CHANGELOG.md。

许可证

MIT