tradallo-reputation
Official@tradallo/reputation
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/reputationstdio를 통해 MCP를 지원합니다.
로컬 개발 / 스테이징
TRADALLO_BASE_URL을 설정하여 자체 배포 환경을 지정하세요:
{
"mcpServers": {
"tradallo-reputation": {
"command": "npx",
"args": ["-y", "@tradallo/reputation"],
"env": { "TRADALLO_BASE_URL": "http://localhost:3000" }
}
}
}Related MCP server: aip-identity
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 helpNO_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
공개 API: https://tradallo.com/api/v1/
공개 키 레지스트리: https://tradallo.com/.well-known/tradallo-pubkeys.json
변경 로그
CHANGELOG.md를 참조하세요.
라이선스
MIT
Available Tools
5 toolsget_track_recordAInspect
Fetch a verified trading track record for a Tradallo profile (human) or agent. Returns cryptographically-verified statistics (Sharpe, win rate, max drawdown, PnL, trade count) computed from on-chain or in-house-sim trade history. The signature is ed25519-verified against Tradallo's published pubkey before this tool returns.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | The Tradallo handle to look up (e.g. 'aaronjordan' for a human, 'alpha-momentum-v3' for an agent). | |
| principal_type | No | Whether the handle is a human profile or an agent. Defaults to 'agent' (the more common reputation-query use case). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that statistics are cryptographically-verified and signature-verified before return, and mentions computation from on-chain or in-house-sim history. Does not cover potential errors or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with purpose and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists return values (Sharpe, win rate, etc.) and explains verification process. Missing pagination or rate limits, but adequate for a simple fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, with clear descriptions for both parameters. The description adds no extra meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a verified trading track record for a Tradallo profile (human or agent) and lists the statistics returned. It distinguishes from siblings like get_utrs and verify_utr by focusing on track record data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when a verified track record is needed, but does not explicitly exclude alternatives or provide when-not scenarios. Sibling tools have different purposes, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_utrsAInspect
Fetch raw Universal Trade Receipts for an agent. Each UTR is a v2 canonical receipt with its SHA-256 hash recomputed by Tradallo so consumers can spot-check individual receipts. Paginated cursor-style on closed_at.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_handle | Yes | The agent's handle. | |
| since | No | ISO timestamp; only return UTRs closed at or after this. Defaults to the agent's anchor. | |
| limit | No | Page size (default 100, max 500). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that each UTR's SHA-256 hash is recomputed for spot-checking, and pagination is cursor-style on closed_at. This reveals behavioral traits beyond a simple fetch, though auth requirements and side effects are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, followed by relevant detail and pagination. No redundant information, every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not fully explain return format or pagination details like cursor handling. It mentions 'v2 canonical receipt' and hash, but an agent might need more clarity on response structure. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, only implicitly relating closed_at to the 'since' parameter via pagination mention. No further parameter details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches raw Universal Trade Receipts for an agent, specifies the resource and action, and distinguishes from siblings by mentioning it provides v2 canonical receipts with recomputed SHA-256 hashes. It also notes pagination, setting it apart from other tools like verify_utr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing the tool's function but lacks explicit guidance on when to use this tool versus its siblings (e.g., get_track_record, verify_utr). No when-not-to-use or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_versionsAInspect
Fetch the full version history of an agent (semver tags, version_hash, policy_hash, when each version was deployed and superseded). Useful for understanding which version of an agent's policy produced a given track record. The response is signature-verified.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_handle | Yes | The agent's handle. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description covers key behaviors: lists return fields and states response is signature-verified. Lacks explicit mention of idempotency or authentication, but sufficient for a read-only fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences, no redundant information, front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and no output schema, the description covers return fields, verification, and a use case. Could specify if history is limited (e.g., pagination), but 'full version history' implies completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for agent_handle. The tool description does not add further information about the parameter beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches full version history with specific fields (semver, hashes, timestamps), distinguishing it from sibling tools that handle track records or UTRs. Includes a use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful context: 'useful for understanding which version of an agent's policy produced a given track record.' Does not explicitly exclude other uses or name alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_recordsAInspect
Search verified trading records by performance filters (Sharpe, max drawdown, trade count, venue, principal type). Returns a list of summary records sorted by the chosen metric. Useful for an agent shopping for strategies that meet specific risk/return criteria. The response is signature-verified against Tradallo's published pubkey before being returned.
| Name | Required | Description | Default |
|---|---|---|---|
| min_sharpe | No | Minimum annualized Sharpe ratio. | |
| min_trades | No | Minimum trade count. | |
| max_drawdown | No | Maximum drawdown as a fraction (e.g. 0.25 for 25%). | |
| venue | No | Restrict to a specific venue (e.g. 'hyperliquid', 'dydx'). | |
| principal_type | No | ||
| sort_by | No | Field to sort results by (descending). Default: net_pnl. | |
| limit | No | Max results (default 25, max 100). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that results are signature-verified, which is a notable behavioral trait. It does not mention authentication, rate limits, or read-only nature, but for a search tool the description is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the main action and parameters, then adds usage context and verification detail efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could have detailed the return fields. 'List of summary records' is vague. However, parameter coverage and sibling context make it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), so the baseline is 3. The description summarizes the filter parameters but adds no new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches verified trading records with performance filters and returns sorted summary records. It distinguishes from sibling get/verify tools by focusing on search and filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is useful when shopping for strategies meeting risk/return criteria, providing clear usage context. It does not mention when not to use it or compare to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_utrAInspect
Look up a Universal Trade Receipt by hash. Returns whether Tradallo has anchored that hash on-chain via a Solana memo transaction, and if so, returns the chain, signature, slot, posted_at, explorer URL, and notarizer pubkey so the caller can independently verify the anchor on Solana Explorer. The signed-envelope response is ed25519-verified before this tool returns.
| Name | Required | Description | Default |
|---|---|---|---|
| utr_hash | Yes | The 64-char hex SHA-256 UTR hash to look up. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully carries the burden and discloses that the response indicates anchoring status, returns detailed verification fields, and involves ed25519 verification before returning. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with front-loaded purpose statement and no redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately explains return fields for a lookup tool with one parameter, though could mention error handling or format of the boolean result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter utr_hash; schema already has a complete description (100% coverage). The description adds no further meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool looks up a Universal Trade Receipt by hash and explains the output structure, distinguishing it from siblings like get_utrs and search_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when you have a UTR hash to verify on-chain anchoring; lacks explicit when-not-to-use or alternatives, but context from sibling names provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.3.2- First observed
get_track_record - First observed
get_utrs - First observed
get_versions - First observed
search_records - First observed
verify_utr
TDQS
Scored across 5 tools
Each tool serves a clear, distinct purpose: fetching a track record, fetching raw receipts, retrieving version history, searching records by filters, and verifying a receipt's on-chain anchor. No two tools overlap in functionality, and descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern (get_track_record, get_utrs, get_versions, search_records, verify_utr), using lowercase with underscores. The naming is predictable and easy to parse.
Five tools is ideal for this domain: they cover the core operations (fetching individual records, listing receipts, version history, search, and verification) without unnecessary bloat. The scope is well-defined and each tool earns its place.
The tool set provides a complete surface for querying and verifying trading reputation data: individual track records, raw receipts, version history, search by filters, and cryptographic verification. No obvious gaps exist for a read-only verification service.
Maintenance
Related MCP Connectors
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Tenzro Network MCP server: wallet, identity, payments, inference, staking, bridges, verification.
MCP server for verifying EUDI/Talao wallet data via OIDC4VP (pull) for AI agents.
Related MCP Servers
- AlicenseAqualityFmaintenanceMCP server for AgentFolio — the identity and reputation layer for AI agents. Query agent profiles, trust scores, verification status, and marketplace listings through 8 MCP tools.989 npm1MIT
- AlicenseAqualityDmaintenanceMCP server for AI agent identity — verify agents with Ed25519 signatures, check trust scores, sign and verify content, exchange encrypted messages. Built on the Agent Identity Protocol (AIP).8MIT
- FlicenseAqualityCmaintenanceReputation and trust scoring service for AI agents, exposed as an MCP server. Evaluate counterparties, report interactions, issue portable trust certificates, and detect Sybil attacks.2353 PyPI-
- AlicenseAqualityBmaintenanceAn MCP server that bridges ERC-8004 agent identity, reputation, and validation registries into tool calls, enabling discovery, inspection, and verification of on-chain AI agents from any MCP client.8MIT