@tradallo/reputation

MCP-Server + TypeScript-Client + CLI für das Tradallo Verified Record Protocol. Drei Wege, um kryptografisch verifizierte Handelsaufzeichnungen von Menschen und Agenten abzufragen:

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

Jede Antwort wird JCS-kanonisiert + ed25519-verifiziert gegen den veröffentlichten Public Key von Tradallo unter tradallo.com/.well-known/tradallo-pubkeys.json, bevor sie angezeigt wird. Die Signatur befindet sich im Envelope; dieser Client ruft das Public-Key-Register ab, löst die key_id auf, verifiziert die Signatur und gibt erst dann die Daten zurück. Replay-Schutz erfolgt über served_at + max_age_seconds.

Installation

Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu (Einstellungen → Entwickler → Konfiguration bearbeiten):

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

Starten Sie Claude Desktop neu. Die Tradallo-Tools sollten in der Werkzeugpalette erscheinen.

Cursor

Fügen Sie dies zu ~/.cursor/mcp.json hinzu (oder über Cursor-Einstellungen → MCP):

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

Generischer MCP-Client

npx @tradallo/reputation

Spricht MCP über stdio.

Lokale Entwicklung / Staging

Verweisen Sie auf Ihre eigene Bereitstellung, indem Sie TRADALLO_BASE_URL setzen:

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

CLI

Die gleiche Binärdatei fungiert als Terminal-CLI, wenn sie mit einem Unterbefehl aufgerufen wird:

# 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 deaktiviert ANSI. TRADALLO_BASE_URL überschreibt die API-Basis-URL.

Programmatischer Client

Binden Sie den verifizierenden Client in Ihren eigenen TS/JS-Code ein:

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.
}

Der Verifizierungsprozess findet INNERHALB von getSigned statt. Wenn etwas fehlschlägt — fehlerhafte Signatur, abgelaufener Envelope, unbekannter Schlüssel, Schema-Nichtübereinstimmung — wirft der Aufruf einen Fehler. Sie sehen niemals unverifizierte Daten.

Tools

get_track_record(handle, principal_type?)

Ruft einen verifizierten Track Record für ein Tradallo-Profil oder einen Agenten ab.

Eingaben:

• handle (String, erforderlich) — das Tradallo-Handle (z. B. aaronjordan, alpha-momentum-v3)

• principal_type ("human" | "agent", optional, Standardwert "agent") — in welchem Namensraum gesucht werden soll

Rückgabe: das vollständige signierte Payload (Verifizierungsstufe, Statistiken für alle Zeiten + rollierend 30/90/365 Tage inklusive Sharpe-Ratio, maximaler Drawdown, Gewinnrate, PnL, Erwartungswert).

Beispielanwendung:

"Zeige mir den verifizierten Handelsverlauf von Aaron Jordan auf Tradallo."

search_records(filters)

Entdecken Sie verifizierte Aufzeichnungen, die Leistungs-Kriterien entsprechen.

Eingaben (alle optional): min_sharpe, min_trades, max_drawdown, venue, principal_type, sort_by, limit.

Rückgabe: sortierte Liste von Zusammenfassungen für Menschen/Agenten mit ihren Statistiken. Signatur-verifiziert.

verify_utr(utr_hash)

Suchen Sie eine Universal Trade Receipt (UTR) anhand ihres Hashes. Gibt zurück, ob Tradallo diesen Hash On-Chain über ein Solana-Memo verankert hat, und falls ja, die Chain, Signatur, Slot, posted_at, Solana Explorer URL und den Public Key des Notarisierers, damit der Aufrufer dies unabhängig On-Chain verifizieren kann.

Rückgabe: { found, anchored_on_chain, chain?, signature?, slot?, posted_at?, explorer_url?, notarizer_pubkey? }.

get_versions(agent_handle)

Ruft den vollständigen Versionsverlauf eines Agenten ab (SemVer-Tags, version_hash, policy_hash, wann jede Version bereitgestellt und ersetzt wurde). Signatur-verifiziert.

get_utrs(agent_handle, since?, limit?)

Ruft rohe Universal Trade Receipts für einen Agenten ab, paginiert im Cursor-Stil basierend auf closed_at. Jede Quittung enthält ihren von Tradallo neu berechneten SHA-256-Hash, damit Konsumenten einzelne Datensätze stichprobenartig prüfen können.

Wie die Verifizierung funktioniert

Jede signierte Tradallo-API-Antwort verpackt die Daten in einen JCS-kanonisierten (RFC 8785) Envelope mit einer ed25519-Signatur:

{
  "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>"
  }
}

Dieser MCP-Server:

1. Ruft /.well-known/tradallo-pubkeys.json ab (5 Min. zwischengespeichert)

2. Löst signature.key_id → ed25519 Public Key auf

3. JCS-kanonisiert {data, schema_version, served_at, max_age_seconds}

4. Verifiziert die Signatur gegen den Public Key

5. Lehnt Antworten ab, bei denen now > served_at + max_age_seconds (Replay-Schutz)

Wenn eine Prüfung fehlschlägt, gibt der Tool-Aufruf einen Fehler zurück, anstatt die Daten. Dem Agenten wird mitgeteilt, warum.

Warum das wichtig ist

Identität (wer ist der Agent) und Zahlungen (wie wird bezahlt) werden 2026 durch x402, MPP, Coinbase Agentic Wallets und ERC-8004 gelöst. Reputation nicht. Wenn ein Agent entscheidet, ob er Kapital delegiert, Trades kopiert oder Signale von einer anderen Partei abonniert, benötigt er eine Möglichkeit zu fragen: "Ist deren Aufzeichnung echt?"

Dieser MCP-Server ist der reibungsärmste Weg, diese Frage zu stellen.

x402 — was kommt

Heute ist die öffentliche API anonym und IP-ratenbegrenzt (60 Anfragen/Min.). Wir führen gestaffelten Zugriff über x402 ein, den HTTP 402 Payment-Required-Standard, damit Agenten USDC-Mikrotransaktionen auf Base bezahlen können, um Ratenbegrenzungen zu umgehen und höhere Durchsatzstufen freizuschalten, ohne Anmeldung oder API-Key-Hürden.

Vorwärtskompatible Erwartungen:

• Anonym: 60 Anfragen/Min./IP (heute, kostenlos)

• Aktiver Abonnent: 600 Anfragen/Min. über API-Key (in Entwicklung — Phase 4.4)

• x402-Mikrozahlung: Pro-Aufruf USDC-Zahlung für einmalige rechenintensive Abfragen; kein Konto erforderlich (geplant Phase 4.5)

• Operator / Flotten-Stufen: Webhook-Abonnements, benutzerdefinierte Subdomains, Prioritäts-Indizierung

Die Ratenbegrenzungs-Antwort wird einen x402-Zahlungsoptionen-Block erhalten, sobald die Facilitator-Pipeline verbunden ist. Dieser MCP-Server wird beginnen, automatisch zu bezahlen, wenn er eine 402 mit x402-Metadaten sieht. Bis dahin sind alle Abfragen kostenlos und verifizierbar.

Referenz-Agent

Ein funktionierender Beispiel-Agent, der Tradallo abfragt, bevor er Kapital delegiert: github.com/tradallo/agent.

Spezifikationen & Dokumentation

• Protokoll-Übersicht: docs/PROTOCOL.md

• Spezifikation: docs/SPEC_V1.1.md

• Öffentliche API: https://tradallo.com/api/v1/

• Public-Key-Register: https://tradallo.com/.well-known/tradallo-pubkeys.json

Changelog

Siehe CHANGELOG.md.

Lizenz

MIT