list_payments

Instructions

Implementation Reference

• src/index.ts:158-181 (registration)

  Registration of the 'list_payments' tool via server.tool(), including tool name and description.

  // Tool 4: List Payments
  server.tool(
    "list_payments",
    "View recent payment history for your CardZero wallet.",
    {
      limit: z.number().optional().describe("Number of records to return (default: 20)"),
      offset: z.number().optional().describe("Number of records to skip for pagination (default: 0)"),
    },
    async ({ limit, offset }) => {
      try {
        const missing = requireWalletId();
        if (missing) return errorResponse("List payments failed", missing);
        const params = new URLSearchParams();
        if (limit !== undefined) params.set("limit", String(limit));
        if (offset !== undefined) params.set("offset", String(offset));
        const query = params.toString() ? `?${params.toString()}` : "";
        const res = await callApi("GET", `/wallets/${WALLET_ID}/payments${query}`);
        if (!res.ok) return errorResponse("List payments failed", res);
        return successResponse(res.json);
      } catch (e) {
        return { content: [{ type: "text" as const, text: `List payments error: ${e}` }], isError: true };
      }
    },
  );

• src/index.ts:162-165 (schema)

  Input schema for list_payments: optional limit (number) and offset (number) with Zod validators and descriptions.

  {
    limit: z.number().optional().describe("Number of records to return (default: 20)"),
    offset: z.number().optional().describe("Number of records to skip for pagination (default: 0)"),
  },

• src/index.ts:166-180 (handler)

  Handler function for list_payments: validates wallet ID, builds query params, calls GET /wallets/{id}/payments API, and returns paginated payment history.

  async ({ limit, offset }) => {
    try {
      const missing = requireWalletId();
      if (missing) return errorResponse("List payments failed", missing);
      const params = new URLSearchParams();
      if (limit !== undefined) params.set("limit", String(limit));
      if (offset !== undefined) params.set("offset", String(offset));
      const query = params.toString() ? `?${params.toString()}` : "";
      const res = await callApi("GET", `/wallets/${WALLET_ID}/payments${query}`);
      if (!res.ok) return errorResponse("List payments failed", res);
      return successResponse(res.json);
    } catch (e) {
      return { content: [{ type: "text" as const, text: `List payments error: ${e}` }], isError: true };
    }
  },

• src/index.ts:64-74 (helper)

  requireWalletId helper: validates that WALLET_ID is set, returns null on success or an ApiResult error object on failure.

  function requireWalletId(): ApiResult | null {
    if (WALLET_ID) return null;
    return {
      ok: false,
      status: 401,
      json: {
        error: "config_missing",
        message: "CARDZERO_WALLET_ID is not set. Get one at https://cardzero.ai",
      },
    };
  }

• src/index.ts:85-89 (helper)

  successResponse helper: formats the API response as a text content block for MCP.

  function successResponse(data: unknown) {
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
    };
  }