@tradallo/reputation

Name: tradallo-reputation
Author: tradallo

npm version license MCP

MCP-сервер + TypeScript-клиент + CLI для протокола Tradallo Verified Record Protocol. Три способа запроса криптографически подтвержденных торговых записей людей и агентов:

# 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";

Каждый ответ проходит JCS-канонизацию и ed25519-проверку по опубликованному публичному ключу Tradallo по адресу tradallo.com/.well-known/tradallo-pubkeys.json перед отображением. Подпись находится в конверте; этот клиент получает реестр публичных ключей, разрешает key_id, проверяет подпись и только после этого возвращает данные. Защита от повторного воспроизведения (replay protection) обеспечивается через 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

Работает с MCP через stdio.

Локальная разработка / стейджинг

Укажите свой собственный адрес развертывания, установив 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 переопределяет базовый 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 (строка, обязательно) — идентификатор Tradallo (например, aaronjordan, alpha-momentum-v3)
principal_type ("human" | "agent", необязательно, по умолчанию "agent") — в каком пространстве имен искать

Возвращает: полный подписанный пакет данных (уровень проверки, статистика за все время + скользящая за 30/90/365 дней, включая коэффициент Шарпа, максимальную просадку, процент побед, PnL, ожидаемую доходность).

Пример использования:

"Покажи мне подтвержденную историю сделок Аарона Джордана на Tradallo."

`search_records(filters)`

Поиск подтвержденных записей, соответствующих критериям эффективности.

Входные данные (все необязательны): min_sharpe, min_trades, max_drawdown, venue, principal_type, sort_by, limit.

Возвращает: отсортированный список сводок по людям/агентам с их статистикой. Подпись проверена.

`verify_utr(utr_hash)`

Поиск универсальной квитанции о сделке (UTR) по хешу. Возвращает информацию о том, закрепил ли Tradallo этот хеш в блокчейне через Solana memo, а если да — сеть, подпись, слот, время публикации, URL в обозревателе Solana и публичный ключ нотариуса, чтобы вызывающая сторона могла независимо проверить данные в блокчейне.

Возвращает: { 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?)`

Получение необработанных универсальных квитанций о сделках для агента, с постраничной навигацией по курсору closed_at. Каждая квитанция включает свой хеш SHA-256, пересчитанный Tradallo, чтобы пользователи могли выборочно проверять отдельные записи.

Как работает проверка

Каждый подписанный ответ API Tradallo упаковывает данные в конверт, канонизированный по 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
Выполняет JCS-канонизацию {data, schema_version, served_at, max_age_seconds}
Проверяет подпись по публичному ключу
Отклоняет ответы, где now > served_at + max_age_seconds (защита от повторного воспроизведения)

Если какая-либо проверка не проходит, вызов инструмента возвращает ошибку вместо данных. Агенту сообщается причина.

Почему это важно

Идентификация (кто является агентом) и платежи (как он платит) решаются в 2026 году с помощью x402, MPP, Coinbase Agentic Wallets и ERC-8004. Репутация — нет. Когда агент решает, делегировать ли капитал, копировать ли сделки или подписываться на сигналы другой стороны, ему нужен способ спросить: "реальна ли их история?"

Этот MCP-сервер — самый простой способ задать этот вопрос.

x402 — что дальше

Сегодня публичный API является анонимным и имеет ограничение по IP (60 запросов/мин). Мы внедряем многоуровневый доступ через x402, стандарт HTTP 402 (требуется оплата), чтобы агенты могли оплачивать микротранзакции в USDC в сети Base для обхода ограничений скорости и получения доступа к более высокопроизводительным уровням без регистрации или использования API-ключей.

Ожидания по обратной совместимости:

Анонимно: 60 запросов/мин/IP (сегодня, бесплатно)
Активный подписчик: 600 запросов/мин через API-ключ (в разработке — Фаза 4.4)
Микроплатеж x402: оплата USDC за каждый вызов для тяжелых запросов; учетная запись не требуется (запланировано на Фазу 4.5)
Уровни оператора / парка агентов: подписки на вебхуки, пользовательские поддомены, приоритетная индексация

Ответ об ограничении скорости получит блок x402 с вариантами оплаты, как только конвейер фасилитатора будет настроен. Этот MCP-сервер начнет автоматически оплачивать запросы, когда увидит код 402 с метаданными x402. До тех пор все запросы бесплатны и проверяемы.

Эталонный агент

Рабочий пример агента, который запрашивает 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