get_utrs

Instructions

Implementation Reference

• src/index.ts:252-263 (handler)

  The MCP tool handler for 'get_utrs' — extracts agent_handle, constructs query string with optional 'since' and 'limit' params, calls client.getSigned() on /api/v1/agents/{handle}/utrs endpoint, and returns verified JSON data.

  case "get_utrs": {
    const handle = String((args as { agent_handle?: unknown })?.agent_handle ?? "").trim();
    if (!handle) return errorResult("agent_handle is required");
    const qs = new URLSearchParams();
    const sinceArg = (args as { since?: unknown })?.since;
    const limitArg = (args as { limit?: unknown })?.limit;
    if (typeof sinceArg === "string") qs.set("since", sinceArg);
    if (typeof limitArg === "number") qs.set("limit", String(limitArg));
    const path = `/api/v1/agents/${encodeURIComponent(handle)}/utrs${qs.toString() ? `?${qs.toString()}` : ""}`;
    const data = await client.getSigned<unknown>(path);
    return jsonResult(data);
  }

• src/index.ts:157-175 (schema)

  Input schema and description for the 'get_utrs' tool registration — defines agent_handle (required), since (optional ISO date-time), and limit (optional integer 1-500) parameters.

  {
    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/index.ts:157-175 (registration)

  Tool named 'get_utrs' registered in the MCP ListToolsRequestSchema handler as part of the tool catalog (line 76-176).

  {
    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/client.ts:117-130 (helper)

  The client.getSigned() helper used by the handler to fetch and cryptographically verify the signed envelope from the Tradallo API.

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