get_versions

Instructions

Implementation Reference

• src/index.ts:243-250 (handler)

  Handler: dispatches get_versions tool calls by extracting agent_handle, validating it, fetching signed version history from the API endpoint /api/v1/agents/{handle}/versions, and returning the verified JSON result.

  case "get_versions": {
    const handle = String((args as { agent_handle?: unknown })?.agent_handle ?? "").trim();
    if (!handle) return errorResult("agent_handle is required");
    const data = await client.getSigned<unknown>(
      `/api/v1/agents/${encodeURIComponent(handle)}/versions`,
    );
    return jsonResult(data);
  }

• src/index.ts:144-156 (schema)

  Schema: Input schema definition for get_versions — requires a single 'agent_handle' string parameter matching pattern ^[a-z0-9_-]+$, with length constraints 1-40.

  {
    name: "get_versions",
    description:
      "Fetch the full version history of an agent: semver tags, version_hash, policy_hash, when each version was deployed and superseded. Use this to understand which version of an agent's policy produced a given track record before delegating capital. Signature-verified.\n\nExample:\n  - get_versions(\"alpha-momentum-v3\")",
    inputSchema: {
      type: "object",
      properties: {
        agent_handle: { type: "string", minLength: 1, maxLength: 40, pattern: "^[a-z0-9_-]+$", description: "The agent's Tradallo handle." },
      },
      required: ["agent_handle"],
    },
    annotations: READ_ONLY_ANNOTATIONS,
  },

• src/index.ts:75-177 (registration)

  Registration: get_versions is registered as the fourth tool in the ListToolsRequestSchema handler, within the tool catalog array returned to MCP clients.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: "get_track_record",
        description:
          "Fetch a verified trading track record for a Tradallo profile (human) or agent. Returns cryptographically-verified statistics (Sharpe, Sortino, win rate, max drawdown, PnL, trade count, expectancy, profit factor) across all-time and rolling 30/90/365-day windows. The signature is ed25519-verified against Tradallo's published pubkey before this tool returns.\n\nExamples:\n  - get_track_record(\"alpha-momentum-v3\") — agent (default)\n  - get_track_record(\"aaronjordan\", \"human\") — human profile",
        inputSchema: {
          type: "object",
          properties: {
            handle: {
              type: "string",
              minLength: 1,
              maxLength: 40,
              pattern: "^[a-z0-9_-]+$",
              description:
                "The Tradallo handle to look up (e.g. 'aaronjordan' for a human, 'alpha-momentum-v3' for an agent). Lowercase letters, digits, hyphens, underscores.",
            },
            principal_type: {
              type: "string",
              enum: ["human", "agent"],
              default: "agent",
              description:
                "Whether the handle is a human profile or an agent. Defaults to 'agent' (the more common reputation-query use case).",
            },
          },
          required: ["handle"],
        },
        annotations: READ_ONLY_ANNOTATIONS,
      },
      {
        name: "search_records",
        description:
          "Discover verified trading records by performance filters. Returns a list of summary records sorted by the chosen metric. Useful when an agent is shopping for strategies that meet specific risk/return criteria rather than looking up a known handle. Every result is signature-verified against Tradallo's published pubkey.\n\nExample:\n  - search_records({ min_sharpe: 1.5, min_trades: 100, max_drawdown: 0.15, sort_by: \"sharpe\", limit: 10 })",
        inputSchema: {
          type: "object",
          properties: {
            min_sharpe: { type: "number", minimum: 0, description: "Minimum annualized Sharpe ratio." },
            min_trades: { type: "integer", minimum: 0, description: "Minimum trade count." },
            max_drawdown: { type: "number", minimum: 0, maximum: 1, description: "Maximum drawdown as a fraction (e.g. 0.25 for 25%)." },
            venue: { type: "string", description: "Restrict to a specific venue (e.g. 'hyperliquid', 'dydx')." },
            principal_type: { type: "string", enum: ["human", "agent"] },
            sort_by: {
              type: "string",
              enum: ["sharpe", "net_pnl", "trade_count", "win_rate"],
              default: "net_pnl",
              description: "Field to sort results by (descending). Default: net_pnl.",
            },
            limit: { type: "integer", minimum: 1, maximum: 100, default: 25, description: "Max results (1-100)." },
          },
        },
        annotations: READ_ONLY_ANNOTATIONS,
      },
      {
        name: "verify_utr",
        description:
          "Look up a Universal Trade Receipt by its SHA-256 hash. Returns whether Tradallo has anchored that hash on-chain via a Solana memo transaction, and if so, the chain, signature, slot, posted_at, Solana Explorer URL, and notarizer pubkey so the caller can independently verify the anchor on chain. The signed envelope is ed25519-verified before this tool returns.\n\nExample:\n  - verify_utr(\"b81f2c7e9a4d5e6f8a3b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f\")",
        inputSchema: {
          type: "object",
          properties: {
            utr_hash: {
              type: "string",
              pattern: "^[0-9a-fA-F]{64}$",
              description: "The 64-char hex SHA-256 UTR hash to look up.",
            },
          },
          required: ["utr_hash"],
        },
        annotations: READ_ONLY_ANNOTATIONS,
      },
      {
        name: "get_versions",
        description:
          "Fetch the full version history of an agent: semver tags, version_hash, policy_hash, when each version was deployed and superseded. Use this to understand which version of an agent's policy produced a given track record before delegating capital. Signature-verified.\n\nExample:\n  - get_versions(\"alpha-momentum-v3\")",
        inputSchema: {
          type: "object",
          properties: {
            agent_handle: { type: "string", minLength: 1, maxLength: 40, pattern: "^[a-z0-9_-]+$", description: "The agent's Tradallo handle." },
          },
          required: ["agent_handle"],
        },
        annotations: READ_ONLY_ANNOTATIONS,
      },
      {
        name: "get_utrs",
        description:
          "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 against `verify_utr`. Paginated cursor-style on closed_at — pass the prior response's `next_since` to advance.\n\nExample:\n  - get_utrs(\"alpha-momentum-v3\", undefined, 50)",
        inputSchema: {
          type: "object",
          properties: {
            agent_handle: { type: "string", minLength: 1, maxLength: 40, pattern: "^[a-z0-9_-]+$", description: "The agent's handle." },
            since: {
              type: "string",
              format: "date-time",
              description: "ISO timestamp; only return UTRs closed at or after this. Defaults to the agent's registration anchor.",
            },
            limit: { type: "integer", minimum: 1, maximum: 500, default: 100, description: "Page size (1-500)." },
          },
          required: ["agent_handle"],
        },
        annotations: READ_ONLY_ANNOTATIONS,
      },
    ],
  }));

• src/cli.ts:290-301 (helper)

  Helper: CLI subcommand 'versions' that hits the same API endpoint /api/v1/agents/{handle}/versions and prints the signed version history as JSON. This is the standalone CLI counterpart to the MCP get_versions tool.

  async function cmdVersions(args: string[]): Promise<void> {
    const handle = args[0];
    if (!handle) {
      console.error("usage: versions <agent_handle>");
      process.exit(2);
    }
    const client = new TradalloClient({ baseUrl: BASE });
    const data = await client.getSigned<unknown>(
      `/api/v1/agents/${encodeURIComponent(handle)}/versions`,
    );
    console.log(JSON.stringify(data, null, 2));
  }