@tradallo/reputation

Name: tradallo-reputation
Author: tradallo

npm version license MCP

Tradallo Verified Record Protocol을 위한 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.com/.well-known/tradallo-pubkeys.json에 게시된 Tradallo의 공개 키를 기준으로 JCS-canonicalized + ed25519-verified 과정을 거칩니다. 서명은 엔벨로프에 포함되어 있으며, 이 클라이언트는 공개 키 레지스트리를 가져와 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 기본 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 프로필 또는 에이전트에 대한 검증된 트랙 레코드를 가져옵니다.

입력값:

handle (문자열, 필수) — Tradallo 핸들 (예: aaronjordan, alpha-momentum-v3)
principal_type ("human" | "agent", 선택 사항, 기본값 "agent") — 검색할 네임스페이스

반환값: 전체 서명된 페이로드 (검증 수준, 전체 및 최근 30/90/365일 통계 포함: 샤프 지수, 최대 낙폭(MDD), 승률, PnL, 기대값).

사용 예시:

"Tradallo에서 Aaron Jordan의 검증된 트레이딩 기록을 보여줘."

`search_records(filters)`

성과 기준에 맞는 검증된 기록을 찾습니다.

입력값 (모두 선택 사항): min_sharpe, min_trades, max_drawdown, venue, principal_type, sort_by, limit.

반환값: 통계가 포함된 인간/에이전트 요약의 정렬된 목록. 서명 검증 완료.

`verify_utr(utr_hash)`

해시로 Universal Trade Receipt를 조회합니다. Tradallo가 Solana 메모를 통해 해당 해시를 온체인에 고정했는지 여부를 반환하며, 고정된 경우 체인, 서명, 슬롯, posted_at, Solana Explorer URL 및 공증인 공개 키를 반환하여 호출자가 온체인에서 독립적으로 검증할 수 있도록 합니다.

반환값: { found, anchored_on_chain, chain?, signature?, slot?, posted_at?, explorer_url?, notarizer_pubkey? }.

`get_versions(agent_handle)`

에이전트의 전체 버전 기록(semver 태그, version_hash, policy_hash, 각 버전이 배포되고 대체된 시점)을 가져옵니다. 서명 검증 완료.

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

에이전트에 대한 원시 Universal Trade Receipt를 가져오며, closed_at 기준 커서 방식의 페이지네이션을 지원합니다. 각 영수증에는 소비자가 개별 기록을 점검할 수 있도록 Tradallo가 재계산한 SHA-256 해시가 포함되어 있습니다.

검증 작동 방식

모든 서명된 Tradallo API 응답은 ed25519 서명이 포함된 JCS-canonicalized (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-canonicalize합니다
공개 키에 대해 서명을 검증합니다
now > served_at + max_age_seconds인 경우 응답을 거부합니다 (리플레이 공격 방지)

검증 중 하나라도 실패하면 도구 호출은 데이터 대신 오류를 반환합니다. 에이전트에게는 실패 이유가 전달됩니다.

이것이 중요한 이유

신원(에이전트가 누구인가)과 결제(어떻게 지불하는가)는 2026년 기준 x402, MPP, Coinbase Agentic Wallets, ERC-8004로 해결되었습니다. 평판은 그렇지 않습니다. 에이전트가 자본을 위임하거나, 거래를 복사하거나, 다른 당사자의 신호를 구독할지 결정할 때 "그들의 기록이 진짜인가?"라고 물을 방법이 필요합니다.

이 MCP 서버는 그 질문을 던지는 가장 마찰 없는 방법입니다.

x402 — 향후 계획

현재 공개 API는 익명이며 IP 속도 제한(60회 요청/분)이 적용됩니다. 우리는 x402 (HTTP 402 결제 필수 표준)를 통해 단계적 액세스를 도입하고 있습니다. 이를 통해 에이전트는 가입이나 API 키 절차 없이 Base에서 USDC 소액 결제를 수행하여 속도 제한을 우회하고 더 높은 처리량 계층을 잠금 해제할 수 있습니다.

향후 호환성 기대치:

익명: 60회 요청/분/IP (현재, 무료)
활성 구독자: API 키를 통해 600회 요청/분 (개발 중 — Phase 4.4)
x402 소액 결제: 일회성 대량 쿼리에 대한 호출당 USDC 결제; 계정 불필요 (Phase 4.5 계획)
운영자 / 플릿 계층: 웹훅 구독, 사용자 지정 하위 도메인, 우선순위 인덱싱

속도 제한 응답은 퍼실리테이터 파이프라인이 연결되면 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