{
  "markdown": "# @tradallo/reputation\n\n[![npm version](https://img.shields.io/npm/v/@tradallo/reputation.svg?style=flat-square)](https://www.npmjs.com/package/@tradallo/reputation)\n[![license](https://img.shields.io/npm/l/@tradallo/reputation.svg?style=flat-square)](./LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet.svg?style=flat-square)](https://modelcontextprotocol.io)\n[![smithery badge](https://smithery.ai/badge/tradallo/reputation)](https://smithery.ai/servers/tradallo/reputation)\n\nMCP server **+ TypeScript client + CLI** for the [Tradallo Verified Record Protocol](https://tradallo.com). Three ways to query cryptographically-verified human and agent trading records:\n\n```bash\n# CLI — pretty terminal cards, no install required\nnpx @tradallo/reputation card alpha-momentum-v3 --agent\n\n# MCP — drop into Claude Desktop / Cursor / any MCP client (config below)\n\n# Programmatic — typed TS/JS client\nimport { TradalloClient } from \"@tradallo/reputation\";\n```\n\nEvery response is **JCS-canonicalized + ed25519-verified** against Tradallo's published pubkey at `tradallo.com/.well-known/tradallo-pubkeys.json` before being surfaced. The signature lives in the envelope; this client fetches the pubkey registry, resolves the `key_id`, verifies the signature, and only then returns the data. Replay protection via `served_at` + `max_age_seconds`.\n\n## Install\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json` (Settings → Developer → Edit Config):\n\n```json\n{\n  \"mcpServers\": {\n    \"tradallo-reputation\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@tradallo/reputation\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The Tradallo tools should appear in the tool palette.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (or via Cursor Settings → MCP):\n\n```json\n{\n  \"mcpServers\": {\n    \"tradallo-reputation\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@tradallo/reputation\"]\n    }\n  }\n}\n```\n\n### Generic MCP client\n\n```bash\nnpx @tradallo/reputation\n```\n\nSpeaks MCP over stdio.\n\n### Local dev / staging\n\nPoint at your own deploy by setting `TRADALLO_BASE_URL`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tradallo-reputation\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@tradallo/reputation\"],\n      \"env\": { \"TRADALLO_BASE_URL\": \"http://localhost:3000\" }\n    }\n  }\n}\n```\n\n## CLI\n\nThe same binary doubles as a terminal CLI when invoked with a subcommand:\n\n```bash\n# Pretty card with verification status, stats, version metadata\nnpx @tradallo/reputation card alpha-momentum-v3 --agent\n\n# Raw verified JSON (for piping into jq, etc.)\nnpx @tradallo/reputation track-record alpha-momentum-v3 --agent\n\n# Discovery\nnpx @tradallo/reputation search --min-sharpe 1.5 --min-trades 200 --sort-by sharpe\n\n# Agent version history\nnpx @tradallo/reputation versions alpha-momentum-v3\n\n# Paginated UTRs\nnpx @tradallo/reputation utrs alpha-momentum-v3 --limit 50\n\n# Look up a specific UTR by hash\nnpx @tradallo/reputation verify <sha256-hex> alpha-momentum-v3\n\n# Help\nnpx @tradallo/reputation help\n```\n\n`NO_COLOR=1` disables ANSI. `TRADALLO_BASE_URL` overrides the API base.\n\n## Programmatic client\n\nEmbed the verifying client in your own TS/JS code:\n\n```ts\nimport { TradalloClient } from \"@tradallo/reputation\";\n\nconst client = new TradalloClient(); // defaults to https://tradallo.com\n\n// Throws if signature invalid, replay window expired, or pubkey unknown.\n// Returns the verified `data` payload (not the envelope wrapper).\nconst record = await client.getSigned<{ stats: { all_time: { sharpe_ratio: number | null } } }>(\n  \"/api/v1/agents/alpha-momentum-v3/track-record\",\n);\n\nif ((record.stats.all_time.sharpe_ratio ?? 0) >= 1.5) {\n  // ... delegate capital, copy trades, etc.\n}\n```\n\nThe verification flow happens INSIDE `getSigned`. If anything fails — bad signature, expired envelope, unknown key, schema mismatch — the call throws. You never see unverified data.\n\n## Tools\n\n### `get_track_record(handle, principal_type?)`\n\nFetch a verified track record for a Tradallo profile or agent.\n\n**Inputs:**\n- `handle` (string, required) — the Tradallo handle (e.g. `aaronjordan`, `alpha-momentum-v3`)\n- `principal_type` (`\"human\"` | `\"agent\"`, optional, default `\"agent\"`) — which namespace to look in\n\n**Returns:** the full signed payload (verification level, all-time + rolling 30/90/365d stats including Sharpe, max drawdown, win rate, PnL, expectancy).\n\n**Example use:**\n> \"Show me Aaron Jordan's verified trading record on Tradallo.\"\n\n### `search_records(filters)`\n\nDiscover verified records matching performance criteria.\n\n**Inputs (all optional):** `min_sharpe`, `min_trades`, `max_drawdown`, `venue`, `principal_type`, `sort_by`, `limit`.\n\n**Returns:** sorted list of human/agent summaries with their stats. Signature-verified.\n\n### `verify_utr(utr_hash)`\n\nLook up a Universal Trade Receipt by hash. Returns whether Tradallo has anchored that hash on-chain via a Solana memo, and if so the chain, signature, slot, posted_at, Solana Explorer URL, and notarizer pubkey so the caller can independently verify on-chain.\n\n**Returns:** `{ found, anchored_on_chain, chain?, signature?, slot?, posted_at?, explorer_url?, notarizer_pubkey? }`.\n\n### `get_versions(agent_handle)`\n\nFetch an agent's full version history (semver tags, version_hash, policy_hash, when each version was deployed and superseded). Signature-verified.\n\n### `get_utrs(agent_handle, since?, limit?)`\n\nFetch raw Universal Trade Receipts for an agent, paginated cursor-style on `closed_at`. Each receipt includes its SHA-256 hash recomputed by Tradallo so consumers can spot-check individual records.\n\n## How verification works\n\nEvery signed Tradallo API response wraps the data in a JCS-canonicalized (RFC 8785) envelope with an ed25519 signature:\n\n```json\n{\n  \"data\": { ... },\n  \"schema_version\": \"1\",\n  \"served_at\": \"2026-04-30T22:29:52.776Z\",\n  \"max_age_seconds\": 60,\n  \"signature\": {\n    \"alg\": \"ed25519\",\n    \"key_id\": \"tradallo-prod-2026-04\",\n    \"sig\": \"<base64>\"\n  }\n}\n```\n\nThis MCP server:\n\n1. Fetches `/.well-known/tradallo-pubkeys.json` (cached 5 min)\n2. Resolves `signature.key_id` → ed25519 public key\n3. JCS-canonicalizes `{data, schema_version, served_at, max_age_seconds}`\n4. Verifies the signature against the pubkey\n5. Rejects responses where `now > served_at + max_age_seconds` (replay protection)\n\nIf any check fails, the tool call returns an error rather than the data. The agent is told why.\n\n## Why this matters\n\nIdentity (who is the agent) and payments (how does it pay) are solved in 2026 by x402, MPP, Coinbase Agentic Wallets, and ERC-8004. **Reputation is not.** When an agent decides whether to delegate capital, copy trades, or subscribe to signals from another party, it needs a way to ask: \"is their record real?\"\n\nThis MCP server is the lowest-friction way to ask that question.\n\n## x402 — what's coming\n\nToday the public API is anonymous and IP-rate-limited (60 req/min). We're rolling out tiered access via [x402](https://x402.org), the HTTP 402 payment-required standard, so agents can pay USDC micro-transactions on Base to bypass rate limits and unlock higher-throughput tiers without any signup or API-key dance.\n\nForward-compatible expectations:\n- Anonymous: 60 req/min/IP (today, free)\n- Active subscriber: 600 req/min via API key (in dev — Phase 4.4)\n- **x402 micro-payment**: per-call USDC payment for one-shot heavy queries; no account required (planned Phase 4.5)\n- Operator / Fleet tiers: webhook subscriptions, custom subdomains, priority indexing\n\nThe rate-limit response will gain an `x402` payment-options block once the facilitator pipeline is wired. This MCP server will start auto-paying when it sees a 402 with x402 metadata. Until then, all queries are free and verifiable.\n\n## Reference agent\n\nA working example agent that queries Tradallo before delegating capital:\n[github.com/tradallo/agent](https://github.com/tradallo/agent).\n\n## Spec & docs\n\n- Protocol overview: [docs/PROTOCOL.md](https://github.com/tradallo/tradallo/blob/main/docs/PROTOCOL.md)\n- Spec: [docs/SPEC_V1.1.md](https://github.com/tradallo/tradallo/blob/main/docs/SPEC_V1.1.md)\n- Public API: https://tradallo.com/api/v1/\n- Pubkey registry: https://tradallo.com/.well-known/tradallo-pubkeys.json\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md).\n\n## License\n\nMIT\n",
  "bytes": 8252,
  "sha": "c6f4a827f14849ceebbae74673c2a460e13d301cb708590371f02d6e58f9340e",
  "repo_slug": "tradallo/reputation",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_tradallo_reputation_05679ac9/readme"
}