search_records

Instructions

Implementation Reference

• src/index.ts:204-217 (handler)

  The 'search_records' tool handler — extracts query params from the incoming arguments (principal_type, min_sharpe, min_trades, max_drawdown, venue, sort_by, limit), builds a URLSearchParams string, calls GET /api/v1/search on the TradalloClient, and returns the signed+verified response as JSON.

  case "search_records": {
    const params = new URLSearchParams();
    const a = (args ?? {}) as Record<string, unknown>;
    if (typeof a.principal_type === "string") params.set("principal_type", a.principal_type);
    if (typeof a.min_sharpe === "number") params.set("min_sharpe", String(a.min_sharpe));
    if (typeof a.min_trades === "number") params.set("min_trades", String(a.min_trades));
    if (typeof a.max_drawdown === "number") params.set("max_drawdown", String(a.max_drawdown));
    if (typeof a.venue === "string") params.set("venue", a.venue);
    if (typeof a.sort_by === "string") params.set("sort_by", a.sort_by);
    if (typeof a.limit === "number") params.set("limit", String(a.limit));
    const path = `/api/v1/search${params.toString() ? `?${params.toString()}` : ""}`;
    const data = await client.getSigned<unknown>(path);
    return jsonResult(data);
  }

• src/index.ts:104-126 (schema)

  Tool registration with inputSchema for 'search_records': defines properties min_sharpe, min_trades, max_drawdown, venue, principal_type, sort_by, limit. sort_by defaults to 'net_pnl', limit defaults to 25, max is 100.

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

• src/index.ts:104-126 (registration)

  The 'search_records' tool is registered in the ListToolsRequestSchema handler as one of five named tools, with description, inputSchema, and readOnly 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,
  },

• src/client.ts:117-130 (helper)

  TradalloClient.getSigned<T>() — the helper that performs the actual HTTP GET request for the search_records handler. It fetches from the API, then verifies the ed25519 signature on the envelope before returning the inner data payload.

  async getSigned<T>(path: string): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      headers: { ...this.headers, accept: "application/json" },
    });
    if (res.status === 404) {
      throw new Error(`not_found: ${path}`);
    }
    if (!res.ok) {
      throw new Error(`request failed: ${res.status} ${res.statusText} (${path})`);
    }
    const envelope = (await res.json()) as SignedEnvelope<T>;
    await this.verifyEnvelope(envelope);
    return envelope.data;
  }