@tradallo/reputation

Name: tradallo-reputation
Author: tradallo

npm version license MCP

用于 Tradallo 验证记录协议的 MCP 服务器 + TypeScript 客户端 + CLI。提供三种查询经加密验证的人类和代理交易记录的方式：

# 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（设置 → 开发者 → 编辑配置）：

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

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

Cursor

添加到 ~/.cursor/mcp.json（或通过 Cursor 设置 → 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 基地址。

编程客户端

将验证客户端嵌入到你自己的 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 个人资料或代理的已验证业绩记录。

输入：

handle (string, 必填) — Tradallo 句柄（例如 aaronjordan, alpha-momentum-v3）
principal_type ("human" | "agent", 可选, 默认 "agent") — 要查找的命名空间

返回： 完整的签名载荷（验证级别、历史总计 + 滚动 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)`

通过哈希查找通用交易收据 (UTR)。返回 Tradallo 是否已通过 Solana 备注将该哈希锚定在链上，如果是，则返回链、签名、槽位、发布时间、Solana 浏览器 URL 和公证人公钥，以便调用者可以独立进行链上验证。

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

`get_versions(agent_handle)`

获取代理的完整版本历史（语义化版本标签、version_hash、policy_hash、每个版本的部署和被取代时间）。签名已验证。

`get_utrs(agent_handle, since?, limit?)`

获取代理的原始通用交易收据，按 closed_at 进行游标分页。每张收据都包含由 Tradallo 重新计算的 SHA-256 哈希，以便消费者可以抽查单条记录。

验证工作原理

每个已签名的 Tradallo API 响应都将数据封装在带有 ed25519 签名的 JCS 规范化 (RFC 8785) 信封中：

{
  "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 服务器：

获取 /.well-known/tradallo-pubkeys.json（缓存 5 分钟）
解析 signature.key_id → ed25519 公钥
对 {data, schema_version, served_at, max_age_seconds} 进行 JCS 规范化
根据公钥验证签名
拒绝 now > served_at + max_age_seconds 的响应（重放保护）

如果任何检查失败，工具调用将返回错误而不是数据。代理会被告知原因。

为什么这很重要

身份（代理是谁）和支付（如何支付）在 2026 年已通过 x402、MPP、Coinbase Agentic Wallets 和 ERC-8004 得到解决。声誉则不然。 当代理决定是否委托资本、复制交易或订阅来自另一方的信号时，它需要一种方式来询问：“他们的记录是真的吗？”

此 MCP 服务器是提出该问题的最低摩擦方式。

x402 — 即将推出

目前，公共 API 是匿名的且受 IP 速率限制（60 次请求/分钟）。我们正在通过 x402（HTTP 402 付费标准）推出分级访问，以便代理可以在 Base 上支付 USDC 微交易，从而绕过速率限制并解锁更高吞吐量的层级，无需任何注册或 API 密钥操作。

前向兼容的预期：

匿名：60 次请求/分钟/IP（目前，免费）
活跃订阅者：通过 API 密钥 600 次请求/分钟（开发中 — 阶段 4.4）
x402 微支付：针对单次重型查询的按调用 USDC 支付；无需账户（计划于阶段 4.5）
运营商/车队层级：Webhook 订阅、自定义子域名、优先级索引

一旦促进器管道连接完毕，速率限制响应将获得一个 x402 支付选项块。此 MCP 服务器将在看到带有 x402 元数据的 402 响应时开始自动支付。在此之前，所有查询都是免费且可验证的。

参考代理

一个在委托资本前查询 Tradallo 的工作示例代理： 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

tradallo-reputation