@tradallo/reputation

Name: tradallo-reputation
Author: tradallo

npm version license MCP

Servidor MCP + cliente TypeScript + CLI para el Protocolo de Registro Verificado de Tradallo. Tres formas de consultar registros de trading de humanos y agentes verificados criptográficamente:

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

Cada respuesta es canonizada mediante JCS + verificada con ed25519 contra la clave pública publicada por Tradallo en tradallo.com/.well-known/tradallo-pubkeys.json antes de ser mostrada. La firma reside en el sobre; este cliente obtiene el registro de claves públicas, resuelve el key_id, verifica la firma y solo entonces devuelve los datos. Protección contra reproducción mediante served_at + max_age_seconds.

Instalación

Claude Desktop

Añade esto a tu claude_desktop_config.json (Ajustes → Desarrollador → Editar configuración):

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

Reinicia Claude Desktop. Las herramientas de Tradallo deberían aparecer en la paleta de herramientas.

Cursor

Añade esto a ~/.cursor/mcp.json (o a través de Ajustes de Cursor → MCP):

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

Cliente MCP genérico

npx @tradallo/reputation

Habla MCP sobre stdio.

Desarrollo local / staging

Apunta a tu propio despliegue configurando TRADALLO_BASE_URL:

{
  "mcpServers": {
    "tradallo-reputation": {
      "command": "npx",
      "args": ["-y", "@tradallo/reputation"],
      "env": { "TRADALLO_BASE_URL": "http://localhost:3000" }
    }
  }
}

CLI

El mismo binario funciona como una CLI de terminal cuando se invoca con un subcomando:

# 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 deshabilita ANSI. TRADALLO_BASE_URL sobrescribe la base de la API.

Cliente programático

Integra el cliente de verificación en tu propio código 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.
}

El flujo de verificación ocurre DENTRO de getSigned. Si algo falla (firma incorrecta, sobre expirado, clave desconocida, discrepancia de esquema), la llamada lanza un error. Nunca verás datos no verificados.

Herramientas

`get_track_record(handle, principal_type?)`

Obtén un historial verificado para un perfil o agente de Tradallo.

Entradas:

handle (cadena, requerido) — el identificador de Tradallo (ej. aaronjordan, alpha-momentum-v3)
principal_type ("human" | "agent", opcional, por defecto "agent") — en qué espacio de nombres buscar

Retorna: el payload firmado completo (nivel de verificación, estadísticas históricas + móviles de 30/90/365 días incluyendo Sharpe, drawdown máximo, tasa de victorias, PnL, esperanza).

Ejemplo de uso:

"Muéstrame el historial de trading verificado de Aaron Jordan en Tradallo."

`search_records(filters)`

Descubre registros verificados que coincidan con criterios de rendimiento.

Entradas (todas opcionales): min_sharpe, min_trades, max_drawdown, venue, principal_type, sort_by, limit.

Retorna: lista ordenada de resúmenes de humanos/agentes con sus estadísticas. Verificado por firma.

`verify_utr(utr_hash)`

Busca un Recibo de Operación Universal (UTR) por hash. Devuelve si Tradallo ha anclado ese hash en la cadena mediante un memo de Solana, y en caso afirmativo, la cadena, firma, slot, posted_at, URL del explorador de Solana y la clave pública del notario para que el llamador pueda verificarlo independientemente en la cadena.

Retorna: { found, anchored_on_chain, chain?, signature?, slot?, posted_at?, explorer_url?, notarizer_pubkey? }.

`get_versions(agent_handle)`

Obtén el historial completo de versiones de un agente (etiquetas semver, version_hash, policy_hash, cuándo se desplegó y reemplazó cada versión). Verificado por firma.

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

Obtén Recibos de Operación Universales crudos para un agente, paginados al estilo cursor en closed_at. Cada recibo incluye su hash SHA-256 recalculado por Tradallo para que los consumidores puedan verificar registros individuales.

Cómo funciona la verificación

Cada respuesta firmada de la API de Tradallo envuelve los datos en un sobre canonizado mediante JCS (RFC 8785) con una firma 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>"
  }
}

Este servidor MCP:

Obtiene /.well-known/tradallo-pubkeys.json (caché de 5 min)
Resuelve signature.key_id → clave pública ed25519
Canoniza mediante JCS {data, schema_version, served_at, max_age_seconds}
Verifica la firma contra la clave pública
Rechaza respuestas donde now > served_at + max_age_seconds (protección contra reproducción)

Si alguna comprobación falla, la llamada a la herramienta devuelve un error en lugar de los datos. Se le informa al agente el motivo.

Por qué es importante

La identidad (quién es el agente) y los pagos (cómo paga) se resuelven en 2026 mediante x402, MPP, Coinbase Agentic Wallets y ERC-8004. La reputación no. Cuando un agente decide si delegar capital, copiar operaciones o suscribirse a señales de otra parte, necesita una forma de preguntar: "¿es real su historial?"

Este servidor MCP es la forma de menor fricción para hacer esa pregunta.

x402 — lo que viene

Hoy en día, la API pública es anónima y tiene límite de tasa por IP (60 req/min). Estamos implementando acceso por niveles mediante x402, el estándar HTTP 402 de pago requerido, para que los agentes puedan pagar microtransacciones en USDC en Base para evitar límites de tasa y desbloquear niveles de mayor rendimiento sin necesidad de registro o gestión de claves API.

Expectativas compatibles hacia adelante:

Anónimo: 60 req/min/IP (hoy, gratis)
Suscriptor activo: 600 req/min mediante clave API (en desarrollo — Fase 4.4)
Micropago x402: pago en USDC por llamada para consultas pesadas de una sola vez; no se requiere cuenta (planificado para Fase 4.5)
Niveles de Operador / Flota: suscripciones a webhooks, subdominios personalizados, indexación prioritaria

La respuesta de límite de tasa obtendrá un bloque de opciones de pago x402 una vez que la tubería del facilitador esté conectada. Este servidor MCP comenzará a pagar automáticamente cuando vea un 402 con metadatos x402. Hasta entonces, todas las consultas son gratuitas y verificables.

Agente de referencia

Un ejemplo de agente funcional que consulta a Tradallo antes de delegar capital: github.com/tradallo/agent.

Especificaciones y documentos

Resumen del protocolo: docs/PROTOCOL.md
Especificación: docs/SPEC_V1.1.md
API pública: https://tradallo.com/api/v1/
Registro de claves públicas: https://tradallo.com/.well-known/tradallo-pubkeys.json

Registro de cambios

Ver CHANGELOG.md.

Licencia

MIT

tradallo-reputation