@tradallo/reputation

Name: tradallo-reputation
Author: tradallo

npm version license MCP

Tradallo Verified Record Protocol用のMCPサーバー + TypeScriptクライアント + CLI です。暗号学的に検証された人間およびエージェントの取引記録をクエリする3つの方法を提供します：

# 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.com/.well-known/tradallo-pubkeys.json で公開されているTradalloの公開鍵に対して 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日の統計。シャープレシオ、最大ドローダウン、勝率、PnL、期待値を含む）。

使用例:

"TradalloでAaron Jordanの検証済み取引記録を見せて。"

`search_records(filters)`

パフォーマンス基準に一致する検証済み記録を検索します。

入力 (すべてオプション): min_sharpe, min_trades, max_drawdown, venue, principal_type, sort_by, limit。

戻り値: 統計情報を含む人間/エージェントの要約のソート済みリスト。署名検証済み。

`verify_utr(utr_hash)`

ハッシュでユニバーサル取引レシート（UTR）を検索します。TradalloがそのハッシュをSolanaメモ経由でオンチェーンにアンカーしているかどうかを返し、アンカーされている場合はチェーン、署名、スロット、posted_at、Solana Explorer 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レスポンスは、データを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サーバーは以下の処理を行います：

/.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リクエスト/分）があります。私たちは、HTTP 402 Payment Required標準である x402 を通じた段階的なアクセスを導入しています。これにより、エージェントは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